On Thu, May 28, 2009 at 09:06, 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?

There are several auto-documentation tools out there, like Sphinx and epydoc, and the stdlib's pydoc. Historically there were other tools, like HappyDoc ad Pythondoc. I'm not up on these or other tools, so I don't know if or how that part of PEP 257 applies. The point of the one-line summary was to allow for tooltips and compact tables of contents. Even if there were no supporting tools, I think it is useful to express the intent of a class/method/function in a single line. The process of distilling the description down can, in itself, be illuminating. To imitate the Zen: if the code can't be described in a short sentence, it may be too complicated. I'm not saying that this should be enforced in any way. It's just a guideline. If a tool needs a short summary and the docstring doens't have a one-liner, I'd expect the tool just to take the first line and add ellipsis ("..."). -- David Goodger http://python.net/~goodger

On 01:06 pm, jeremy@alum.mit.edu wrote:

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?

For what it's worth, https://launchpad.net/pydoctor appears to do this, as you can see from the numerous truncated sentences on http://twistedmatrix.com/documents/8.2.0/api/moduleIndex.html. I suspect a more reasonable approach for automatic documentation generators would be to try to identify the first complete sentence, rather than the first line... but, this is at least an accurate description of the status quo for some tools :).