PEP 257: Docstring Conventions
rnd at onego.ru
Wed Jun 13 08:17:24 CEST 2001
I have some questions about docstrings:
1. Are the existing docstrings in Python standard modules
example of good docstrings according to this PEP?
2. Each time I wonder about this:
- The docstring is a phrase ending in a period. It prescribes the
function's effect as a command ("Do this", "Return that"), not
as a description: e.g. don't write "Returns the pathname ..."
Does it mean that docstring must describe interface, not
But then again:
The docstring for a function or method should
1. summarize its behavior
2.1. its arguments,
2.2. return value(s),
2.3. side effects
2.4. exceptions raised
2.5. restrictions on when it can be called (all if applicable).
... Optional arguments should be indicated.
... It should be documented whether keyword arguments are part of the
That is, docstring has nothing to do with internals of the
Sincerely yours, Roman A.Suzi
- Petrozavodsk - Karelia - Russia - mailto:rnd at onego.ru -
More information about the Python-list