convention for documenting function parameters in doc strings

D

danielx

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).
 
J

Jean-Michel Pichavant

danielx said:
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
 
D

danielx

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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top