[Doc-SIG] epydoc reST markup for stdlib docstrings

[Fred Drake]

On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> The ", optional" parts seem rather redundant (since they are implied by
> the function signature itself), but the guidelines say to include them,
> so I included them. It seems to me that the exceptional keyword
> arguments are those which are required, not those which are optional.

This has always been a source of tension in documenting Python: a
certain amount of information is available in the signature, but the
signature of the implementation function isn't always the same as the
signature of the contract.  Documentation needs the later.

Interfaces help, if you use them (ABCs kinda, if you follow that
school of thought).  Unfortunately, there's not really a way currently
to tell the difference between "default implementation" and "contract"
in ABCs, which is all stock Python provides.


  -Fred

-- 
Fred L. Drake, Jr.    <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Mille