[Doc-SIG] epydoc reST markup for stdlib docstrings

[Nick Coghlan]

Barry Warsaw wrote:
> 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
>     """

Since the NumPy conventions seem to be the only real alternative
proposed so far, here's what the above would look like (according to my
ever so comprehensive 5 minute skim of those guidelines, anyway...)

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

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

Basically, the numpy format trades a couple of lines of whitespace for
the section header to get rid of the tag noise in the individual
parameter descriptions.

The ", optional" parts seem rather redundant (since they are implied by
the function signature itself), but the guidelines say to include them,
so I included them. It seems to me that the exceptional keyword
arguments are those which are required, not those which are optional.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------