[Python-checkins] cpython (2.7): Advertise nesting directives for class/method and class/data combos.

[eric.araujo]

http://hg.python.org/cpython/rev/c882b5ff92d9
changeset:   69768:c882b5ff92d9
branch:      2.7
parent:      69704:1a45c92f9716
user:        Éric Araujo <merwok at netwok.org>
date:        Sat Apr 16 23:47:53 2011 +0200
summary:
  Advertise nesting directives for class/method and class/data combos.

Also fix a typo and a misleading example (method used to describe function).

files:
  Doc/documenting/markup.rst |  25 +++++++++++++++++++++----
  1 files changed, 21 insertions(+), 4 deletions(-)


diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -152,7 +152,7 @@
 
    Describes global data in a module, including both variables and values used
    as "defined constants."  Class and object attributes are not documented
-   using this environment.
+   using this directive.
 
 .. describe:: exception
 
@@ -165,7 +165,7 @@
    parameters, enclosing optional parameters in brackets.  Default values can be
    given if it enhances clarity.  For example::
 
-      .. function:: Timer.repeat([repeat=3[, number=1000000]])
+      .. function:: repeat([repeat=3[, number=1000000]])
 
    Object methods are not documented using this directive. Bound object methods
    placed in the module namespace as part of the public interface of the module
@@ -186,13 +186,30 @@
 
    Describes an object data attribute.  The description should include
    information about the type of the data to be expected and whether it may be
-   changed directly.
+   changed directly.  This directive should be nested in a class directive,
+   like in this example::
+
+      .. class:: Spam
+
+            Description of the class.
+
+            .. data:: ham
+
+               Description of the attribute.
+
+   If is also possible to document an attribute outside of a class directive,
+   for example if the documentation for different attributes and methods is
+   split in multiple sections.  The class name should then be included
+   explicitly::
+
+      .. data:: Spam.eggs
 
 .. describe:: method
 
    Describes an object method.  The parameters should not include the ``self``
    parameter.  The description should include similar information to that
-   described for ``function``.
+   described for ``function``.  This method should be nested in a class
+   method, like in the example above.
 
 .. describe:: opcode
 

-- 
Repository URL: http://hg.python.org/cpython