Unfortunately PEP 257 falls short on specifying how to describe arguments -- it has only one example, it's not normative, and there's not much code that follows the example. The reST conventions are more common, but the stdlib itself rarely uses them. It would be nice to come up with a better convention that takes PEP 484 into account (so doc generators can incorporate the argument type annotations into the generated output, merged with per-argument from the docstring). On Mon, Jan 19, 2015 at 11:25 AM, Ian Cordasco <graffatcolmingov@gmail.com> wrote:
There's also PEP 0257 for docstring formatting.
On Mon, Jan 19, 2015 at 12:51 PM, Ben Finney <ben+python@benfinney.id.au> wrote:
Cem Karan <cfkaran2@gmail.com> writes:
OK, so should there be a convention for writing docstrings?
The current convention is to use Sphinx to render a reStructuredText docstring, and write the API of a class or function with reStructuredText field lists.
<URL:http://sphinx-doc.org/domains.html#the-python-domain> <URL:http://sphinx-doc.org/domains.html#info-field-lists>
Python's own documentation, as well as a large amount of third-party packages, are written this way.
-- \ “It is seldom that liberty of any kind is lost all at once.” | `\ —David Hume | _o__) | Ben Finney
_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
-- --Guido van Rossum (python.org/~guido)