[Python-Dev] question about docstring formatting

[Jeremy Hylton]

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