convention for documenting function parameters in doc strings

[Jean-Michel Pichavant]

danielx wrote:
> Is there a convention for 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 equivalent convention I (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