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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
