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

[David Goodger]

on 2001-06-19 12:30 PM, Sam Penrose (sam@ddmweb.com) wrote:
> What is readable depends in on context. I think Guido's
> Style Guide is basically great but too specific in some ways and not
> specific enough in others to use as a spec. The Guide mashes together
> commentary which, when made a spec, is appropriate for differing
> contexts:
...
> What is style and what is spec?
> 
> 4) To be crystal clear: I would like to see a clear line between which
> standards can be violated at the cost of dirty looks and which will
> cause DSP code to fail, and I'd like to see some of the current PEP
> contents explicitly moved to the first category.

These are valid points. I will work on making changes to the PEP. Any help
you (or anyone) could give, such as specific "this is style and that is
spec", or complete rewrites ;-) would be very welcome and helpful.

> this-opinion-is-worth-what-you-paid-for-it-ly,

Far, FAR more, to be sure. Thank you.

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