PEP 257: Docstring Conventions

[David Goodger]

on 2001-06-13 2:17 AM, Roman Suzi (rnd at onego.ru) wrote:
> 1. Are the existing docstrings in Python standard modules
> example of good docstrings according to this PEP?

Some are, some aren't. Not everybody has read Guido's Python Style Guide
(the source of 98% of the PEP), and not everybody who *has* read it applies
it. Part of the motivation for making this into PEP was to standardize
docstrings so that tools can extract useful information.

> Does it mean that docstring must describe interface, not
> implementation?

Yes. Implementations frequently change.

> That is, docstring has nothing to do with internals of the
> function?

Typically, yes.

Docstrings are how a module/class/method/function advertises its services to
the Python world. "This is how to call me, this is what I'll do for you,
this is what I'll give back."

-- 
David Goodger    dgoodger at 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