PEP 257: Docstring Conventions

[Delaney, Timothy]

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

That seems correct to me. The docstring should have enough information for
you to be able to use the function/class/etc as a black box - you put things
in one end, and something else (maybe) comes out the other.

Internals documentation should be in the form of comments. After all (in
theory), why should you need to worry about the internals unless you're
looking at the source?

Tim Delaney