On Feb 8, 2:49 am, Jean-Michel Pichavant <jeanmic...@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. -- http://mail.python.org/mailman/listinfo/python-list