diff options
author | Éric Araujo <merwok@netwok.org> | 2011-04-16 23:47:53 +0200 |
---|---|---|
committer | Éric Araujo <merwok@netwok.org> | 2011-04-16 23:47:53 +0200 |
commit | 130e37365eb36a21ebd8c52ad8a69f045a61364f (patch) | |
tree | 70a0514af7ec64b01269505bb4e433aa11d7b539 | |
parent | 14fb1a9901d0b5eb9142ef69bd26906a07543d93 (diff) | |
download | cpython-130e37365eb36a21ebd8c52ad8a69f045a61364f.tar.gz |
Advertise nesting directives for class/method and class/data combos.
Also fix a typo and a misleading example (method used to describe function).
-rw-r--r-- | Doc/documenting/markup.rst | 25 |
1 files changed, 21 insertions, 4 deletions
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index d7d23cd0b4..d68e909137 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -152,7 +152,7 @@ The directives are: 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 @@ The directives are: 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 @@ The directives are: 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 |