PEP 257: Docstring Conventions

[Roman Suzi]

Hello, 

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

But then again:

    The docstring for a function or method should 
1. summarize its behavior
2. document 
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
interface.

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

-- 
http://mail.python.org/mailman/listinfo/python-list

Sincerely yours, Roman A.Suzi
-- 
 - Petrozavodsk - Karelia - Russia - mailto:rnd at onego.ru -