convention for documenting function parameters in doc strings

danielx danielwong at berkeley.edu
Mon Feb 8 01:06:14 EST 2010


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



More information about the Python-list mailing list