Re: epydoc reST markup for stdlib docstrings

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

_______________________________________________
Doc-SIG maillist  -  [email protected]
http://mail.python.org/mailman/listinfo/doc-sig

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iQIcBAEBCAAGBQJLxbDTAAoJEBJutWOnSwa/Xz0QALKVgnYUTYORLNM27ytxqQfz
xxAhu57wRgh/r7xdB/x8vSMekjize4Wqn7VAzUtfi+EhHIG3n9v1HKtApF2mie73
tcumlXG5kc/udKnCinboFera8FP5E5Ycnlo23GWhCsVRrN4W6GdQCCPaqB1YIdfS
/6Q6Aez5U83c2yjLiPaYLUTgOfHPnWHcjf7LKRXGBOOhC1divoH7SxoNlcE9Iwbu
WVkpZeH3MroxKG9Zb3Ob7DPfUpIyLVPN37V0C0rmdYEtjqWmwpgJozrmIGh1OUtA
50X4SZCs0P9ingpW0u3B62l67LwGgH/mPRo3ukQaOGtg8rcV38st7mPpPpIVvddY
c5f+QZh09mCg7Adu6PbO4H9iQkBwQ+gorZj+372W23ljwwHLUWyx76Fk/PSa2HGI
4Aw2DnNAPC0/QyELwQ/OPcDW/MRAmisVyH3J6BAWKD/OOR687MNgqb+C84RwI1VJ
hyik+y9TjVHmnvFJeK6J+cAo3854EQE9rpqqgGKHehEbuUR2liZhrLZcIhII/4ux
gpX8neLeOmh931Stn7sb3OQLlO/GVKIXYedNqqO2qnIxkJMFSiAqWUu6P3Jw+7+5
d3IZvuJk3iQoSavm21H80thKo1Q/iTwrxMDw158Vakc7EIw6L46WPVy4Z0GRer3K
ullSplFuePPRJZUOVC9u
=YD3i
-----END PGP SIGNATURE-----