[Doc-SIG] epydoc reST markup for stdlib docstrings

[Barry Warsaw]

On Apr 14, 2010, at 02:44 PM, Michael Foord wrote:

>I'm not aware of other formats beyond epydoc and javadoc (I agree with 
>your opinion on javadoc) - oh and the .NET xml format which I strongly 
>recommend we steer clear of. Do you have any references?

XML is not human readable or writable (IMNSHO :).

As far as epydoc, this is probably the only page you care about:

http://epydoc.sourceforge.net/manual-fields.html

It describes the fields that are used to describe parameters, return types,
and exceptions.

Note that while the body of that page uses "Epytext" format, the table near
the top of the page shows the three alternative syntaxes.  Of those of course
I recommend reST (the middle column).  You have to mentally translate the
syntax in the body of the page to reST though.

Keep in mind too that it's not always necessary to include *every* field in a
function's docstring.  Obviously, include only what is useful to the consumer
of the function's documentation.  For example, when it's completely obvious,
or when I actually don't know (e.g. because the method proxies some other
method 3 levels deep), I might not include the :type: field.  I also won't
include obvious, common exceptions.  I do think *that* can be left to the
author's taste.

Here's an example:

def inject_message(mlist, msg, recips=None, switchboard=None, **kws):
    """Inject a message into a queue.

    :param mlist: The mailing list this message is destined for.
    :type mlist: `IMailingList`
    :param msg: The message object to inject.
    :type msg: `email.message.Message` or derived
    :param recips: Optional set of recipients to put into the message's
        metadata.
    :type recips: sequence of strings
    :param switchboard: Optional name of switchboard to inject this message
        into.  If not given, the 'in' switchboard is used.
    :type switchboard: string
    :param kws: Additional values for the message metadata.
    :type kws: dictionary
    """

Note that :param: values are complete sentences, while :type: values are
informative types, not necessarily explicit types (e.g. an interface for mlist
and 'string' instead of 'str' or 'unicode' for switchboard).  This function
doesn't return anything and doesn't explicitly raise any exceptions.  The
implicit KeyErrors that could be raised are not described.

>I don't recall *ever* seeing a consistent pattern for specifying 
>parameters and return values in Python docstrings.

Exactly. :)

>I too would prefer a consistent pattern be adopted for the Python 
>standard library. Good luck finding someone to go and change all the 
>docstrings in the standard library to use it...

Like all other coding standards we have for the stdlib, the migration can
happen opportunistically over time.  But folks need a target or nothing will
ever happen.

-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/3c814481/attachment.pgp>