From 828beb12e06dee86f478a31c5d1cb091ed2e224e Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 29 Jun 2019 18:43:30 +0900 Subject: [PATCH] doc: Update document for :annotation: option (refs: #6495) --- doc/usage/extensions/autodoc.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 8fdee214b..74c0b609d 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -243,21 +243,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, These work exactly like :rst:dir:`autoclass` etc., but do not offer the options used for automatic member documentation. - :rst:dir:`autodata` and :rst:dir:`autoattribute` support - the ``annotation`` option. - Without this option, the representation of the object - will be shown in the documentation. - When the option is given without arguments, - only the name of the object will be printed:: + :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation`` + option. The option controls how the value of variable is shown. If specified + without arguments, only the name of the variable will be printed, and its value + is not shown:: .. autodata:: CD_DRIVE :annotation: - You can tell sphinx what should be printed after the name:: + If the option specified with arguments, it is printed after the name as a value + of the variable:: .. autodata:: CD_DRIVE :annotation: = your CD device name + By default, without ``annotation`` option, Sphinx tries to obtain the value of + the variable and print it after the name. + For module data members and class attributes, documentation can either be put into a comment with special formatting (using a ``#:`` to start the comment instead of just ``#``), or in a docstring *after* the definition. Comments