Proposal to extend PEP 257 (New Documentation String Spec)

[Ben Finney]

rantingrick <rantingrick at 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