[Python-Dev] question about docstring formatting

[David Goodger]

On Thu, May 28, 2009 at 09:06, Jeremy Hylton <jeremy at alum.mit.edu> 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>