From 130e37365eb36a21ebd8c52ad8a69f045a61364f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 16 Apr 2011 23:47:53 +0200 Subject: Advertise nesting directives for class/method and class/data combos. Also fix a typo and a misleading example (method used to describe function). --- Doc/documenting/markup.rst | 25 +++++++++++++++++++++---- 1 file 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 -- cgit v1.2.1