[Python-Dev] question about docstring formatting

[Ron Adam]

Jeremy Hylton wrote:
> 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

Python's own built in help utility, pydoc uses it.

At the help prompt in the python console window, type "modules searchkey" 
to get a list of modules that contain the searchkey in thier one line summary.

Running pydoc with the -g option opens a tkinter search window, that 
searches the summery lines.  Selecting from that list then opens the 
browser to that item.

Ron