[Doc-SIG] Re: PEP 257: Docstring Conventions

[David Goodger]

on 2001-06-13 4:45 PM, Sam Penrose (sam@ddmweb.com) wrote:
>>>> This is a PEP-ification of part of Guido van Rossum's Python Style
> Guide ... <<<
> 
> parts of the Style Guide weather the conversion to a specification
> better than others. For example...
[omitted]
> .... seems a bit visually oriented for the purpose of making
> docstrings machine-parseable.

Making docstrings machine-parsable is not the point of PEP 257, nor of the
Style Guide from which it sprang. The point is to standardize the high-level
structure of docstrings: what should they contain, and how to say it
(without touching on any markup syntax within docstrings). Docstring spacing
is one of the conventions that make Python code readable, IMHO. The
Docstring Processing System is made up of layers of specs. PEP 257 is the
highest-level, semantic part.

The PEP contains conventions, not laws or syntax. If you violate the
conventions, the worst you'll get is some dirty looks. But the DPS will know
about some of the conventions, so following them will get you the best
results.

BTW, what's wrong with that specific convention?

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net