# HG changeset patch
# User JeanPierre Flori
# Date 1332265553 3600
# Node ID 6ae87d84ec503b28ab3a7240a9dd7becfe63c803
# Parent e7d3eef7fcfd286a6483d9daf2eafebd518b50b0
#11521: Reviewer patch
diff git a/sage/categories/homset.py b/sage/categories/homset.py
 a/sage/categories/homset.py
+++ b/sage/categories/homset.py
@@ 1,6 +1,39 @@
"""
+r"""
Homsets
+The class :class:`Hom` is the base class used to represent sets of morphisms
+between objects of a given category.
+:class:`Hom` objects are usually "weakly" cached upon creation so that they
+don't have to be generated over and over but can be garbage collected together
+with the corresponding objects when these are are not stongly ref'ed anymore.
+
+EXAMPLES:
+
+In the following, the :class:`Hom` object is indeed cached::
+
+ sage: K = GF(17)
+ sage: H = Hom(ZZ, K)
+ sage: H
+ Set of Homomorphisms from Integer Ring to Finite Field of size 17
+ sage: H is Hom(ZZ, K)
+ True
+
+Nonetheless, garbage collection occurs when the original references are
+overwritten::
+
+ sage: for p in prime_range(200):
+ ... K = GF(p)
+ ... H = Hom(ZZ, K)
+ ...
+ sage: import gc
+ sage: _ = gc.collect()
+ sage: from sage.rings.finite_rings.finite_field_prime_modn import FiniteField_prime_modn as FF
+ sage: L = [x for x in gc.get_objects() if isinstance(x, FF)]
+ sage: len(L)
+ 2
+ sage: L
+ [Finite Field of size 2, Finite Field of size 199]
+
AUTHORS:
 David Kohel and William Stein
@@ 29,8 +62,6 @@
# http://www.gnu.org/licenses/
#*****************************************************************************
import weakref

from sage.categories.category import Category
import morphism
from sage.structure.parent import Parent, Set_generic
@@ 81,8 +112,8 @@
sage: Hom(FreeModule(QQ,1), FreeModule(ZZ,1))
Set of Morphisms from Vector space of dimension 1 over Rational Field to Ambient free module of rank 1 over the principal ideal domain Integer Ring in Category of vector spaces over Rational Field
 Here, we test against a memory leak that has been fixed at #11521 by using
 a weak cache::
+ Here, we test against a memory leak that has been fixed at :trac:`11521` by
+ using a weak cache::
sage: for p in prime_range(10^5):
... K = GF(p)