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

[Sam Penrose]

>>> 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...

"Insert a blank line before and after all docstrings (one-line or
multi-line) that document a class -- generally speaking, the    
class's methods are separated from each other by a single blank    
line, and the docstring needs to be offset from the first method by
a blank line; for symmetry, put a blank line between the class    
header and the docstring.  Docstrings documenting functions    
generally don't have this requirement, unless the function's body    
is written as a number of blank-line separated sections -- in this    
case, treat the docstring as another section, and precede it with a
blank line."

... seems a bit visually oriented for the purpose of making
docstrings machine-parseable. I would prefer to see only things which
further the (wonderful; hear hear!) goals of the doc-sig made into
specifications. Which will require editing years-old BDFL
pronouncements.

Cheers,
S