rantingrick <rantingr...@gmail.com> writes:
> ---------------------------------------
> New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
> {ARGUMNET_1} <{TYPE}>:
> ARGUMENT_1_DESCRIPTION}
> {ARGUMNET_2} <{TYPE}>:
> ARGUMENT_2 DESCRIPTION}
> {ARGUMNET_N} <{TYPE}>:
> ARGUMENT_N_DESCRIPTION}
> {NEWLINE}
> """
I use reStructuredText formatting in my PEP 257 docstrings:
def frobnicate(spong, mode="wibble"):
""" Frobnicate the spong.
:param spong: The SpongDrabble instance to be frobnicated.
:param mode: Specific frobnication mode to use. Valid modes
are "wibble", "wobble", "warble".
:return: The blagule from the frobnication.
Note that the Weebly-Ruckford algorithm is used for
frobnication portability. See
<http://ruckford.example.com/>_ for details.
"""
pass
pass
pass
I would be happy to see these conventions be more formalised; after all,
reStructuredText was originated as a means of formatting documentation
in Python docstrings.
--
\ “All opinions are not equal. Some are a very great deal more |
`\ robust, sophisticated and well supported in logic and argument |
_o__) than others.” —Douglas Adams |
Ben Finney
--
http://mail.python.org/mailman/listinfo/python-list
