# HG changeset patch
# User Vincent Delecroix <20100.delecroix at gmail.com>
# Date 1370111480 7200
# Node ID fd406f143ab76968c02abde454d03d325b733945
# Parent 61da1546218b873d0909365e3bcbb4c9c8ef5baf
trac 10193: documentation issues
 improve the main docstring of the category SetsWithGrading
 add the example in the documentation
diff git a/doc/en/reference/categories/index.rst b/doc/en/reference/categories/index.rst
 a/doc/en/reference/categories/index.rst
+++ b/doc/en/reference/categories/index.rst
@@ 162,6 +162,7 @@
sage/categories/examples/semigroups
sage/categories/examples/semigroups_cython
sage/categories/examples/sets_cat
+ sage/categories/examples/sets_with_grading
sage/categories/examples/with_realizations
Miscellaneous
diff git a/sage/categories/examples/sets_with_grading.py b/sage/categories/examples/sets_with_grading.py
 a/sage/categories/examples/sets_with_grading.py
+++ b/sage/categories/examples/sets_with_grading.py
@@ 1,5 +1,5 @@
r"""
An example of graded set: nonnegative integers graded by themselves.
+Examples of a set with grading
"""
from sage.structure.parent import Parent
diff git a/sage/categories/sets_with_grading.py b/sage/categories/sets_with_grading.py
 a/sage/categories/sets_with_grading.py
+++ b/sage/categories/sets_with_grading.py
@@ 31,20 +31,20 @@
sets. The *grading* function maps each element `s` of
`S` to its *grade* `i`, so that `s\in S_i`.
 From implementation point of view, if the graded set is enumerated then
 each graded component should be enumerated (there is a check in the method
 :meth:`~SetsWithGrading.ParentMethods._test_graded_components`). The
 contrary needs not be true.

 To implement this category, a parent must either implement
+ A parent with this category must either implement
:meth:`~SetsWithGrading.ParentMethods.graded_component()` or
:meth:`~SetsWithGrading.ParentMethods.subset()`. The first argument to
:meth:`~SetsWithGrading.ParentMethods.subset()` must be the grading for
compatibility with
 :meth:`~SetsWithGrading.ParentMethods.graded_component()` if both methods
 are not implemented. Additionally either the parent must implement
 :meth:`~SetsWithGrading.ParentMethods.grading()` or its elements will need
 a method ``grade()``.
+ :meth:`~SetsWithGrading.ParentMethods.graded_component()`.
+ Additionally either the parent must implement
+ :meth:`~SetsWithGrading.ParentMethods.grading()` or its elements must
+ a method ``grade()``. See the example in
+ :class:`sage.categories.examples.sets_with_grading.NonNegativeIntegers`)
+
+ Finally, if the graded set is enumerated (see
+ :class:`~sage.categories.enumerated_sets.EnumeratedSets`) then each graded
+ component should be enumerated. The contrary needs not be true.
EXAMPLES: