# HG changeset patch
# User Simon King
# Date 1345141378 -7200
# Node ID 6658e3bc3e1f9c6d8eb2176895842e4ef04d4484
# Parent 8a55ce250af80970145c467e6a35bf6794800218
#715: Documentation of TripleDict
diff --git a/doc/en/reference/structure.rst b/doc/en/reference/structure.rst
--- a/doc/en/reference/structure.rst
+++ b/doc/en/reference/structure.rst
@@ -9,6 +9,7 @@
sage/structure/parent_old
sage/structure/parent_base
sage/structure/parent_gens
+ sage/structure/coerce_dict
sage/structure/formal_sum
sage/structure/factorization
sage/structure/element
diff --git a/sage/structure/coerce_dict.pyx b/sage/structure/coerce_dict.pyx
--- a/sage/structure/coerce_dict.pyx
+++ b/sage/structure/coerce_dict.pyx
@@ -1,13 +1,35 @@
#*****************************************************************************
# Copyright (C) 2007 Robert Bradshaw
-# 2011 Simon King
+# 2012 Simon King
#
# Distributed under the terms of the GNU General Public License (GPL)
#
# http://www.gnu.org/licenses/
#*****************************************************************************
+"""
+Containers for storing coercion data
+This module provides :class:`TripleDict`. It is a structure similar to
+``WeakKeyDictionary`` in Python's weakref module, and is optimized for lookup
+speed. Keys consist of a triple (k1,k2,k3) and are looked up by identity
+rather than equality. The keys are stored by weakrefs if possible. If any
+one of the components k1, k2, k3 gets garbage collected, then the entry is
+removed from the :class:`TripleDict`.
+Key components that do not allow for weakrefs are stored via a normal
+refcounted reference. That means that any entry stored using a triple
+(k1,k2,k3) so that none of the k1,k2,k3 allows a weak reference behaves
+as an entry in a normal dictionary: Its existence in :class:`TripleDict`
+prevents it from being garbage collected.
+
+That container currently is used to store coercion and conversion maps
+between two parents (:trac:`715`) and to store homsets of pairs of objects
+of a category (:trac:`11521`). In both cases, it is essential that the parent
+structures remain garbage collectable, it is essential that the data access
+is faster than with a usual ``WeakKeyDictionary``, and we enforce the "unique
+parent condition" in Sage (parent structures should be identical if they are
+equal).
+"""
include "../ext/python_list.pxi"
from sage.misc.constant_function import ConstantFunction