convention for documenting function parameters in doc strings

[danielx]

On Feb 8, 2:49 am, Jean-Michel Pichavant <jeanmic... at sequans.com>
wrote:
> danielx wrote:
> > Is there aconventionfor how to document function (or method)
> > parameters in doc strings? Recently, I've been doing alot of PHP
> > programming, and in PHPdoc, you'd do it like this:
>
> > /*
> >  * @param type $foo Description.
> >  *
> >  * @return type Description.
> >  */
> > function bar($foo) {
> >   ...
> > }
>
> > Is there an equivalentconventionI (c|sh)ould be using in my Python
> > docstrings? I saw that Python 3 has function annotations, which could
> > be used for this purpose, but function annotations have no particular
> > purpose within the language itself (which seems like a mistake to me),
> > and they don't exist in the Python 2.x series (at least not the older
> > versions).
>
> Different strategies here:
>
> 1/ most doc builders propose their own format. You can stick to it if
> you don't want to use another builder (e.g. epydoc has a specific syntax
> to document signatures)
> 2/ Use a 'standard' format, usually these formats are a bit more formal
> but they gain in portability, most builders support these formats.
> reStructuredText is one of them and supported by all python doc builders.
>
> http://epydoc.sourceforge.net/manual-othermarkup.html
>
> JM

Thanks for the link, Jean-Michel. I was hoping to find out more about
how this is don in reStructuredText, since that seems to be what's
used to document Python at docs.python.org. There is a section in the
page that you linked to which describes how documenting function
parameters in reST works, which seems to be what I was looking for.