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

Mon May 2 13:39:10 CEST 2011

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
