[Python-Dev] question about docstring formatting (original) (raw)
Jeremy Hylton jeremy at alum.mit.edu
Thu May 28 15:06:03 CEST 2009
- Previous message: [Python-Dev] Survey on DVCS usage and experience
- Next message: [Python-Dev] question about docstring formatting
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
A question came up at work about docstring formatting. It relates to the description of the summary line in PEP 257.
http://www.python.org/dev/peps/pep-0257/ """Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first line (see example below)."""
It says that the summary line may be used by automatic indexing tools, but is there any evidence that such a tool actually exists? Or was there once upon a time? If there are no such tools, do we still think that it is important that it fits on line line?
Jeremy
- Previous message: [Python-Dev] Survey on DVCS usage and experience
- Next message: [Python-Dev] question about docstring formatting
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]