On 14/04/2010 16:37, Fred Drake wrote:
On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan<ncogh...@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.
Right - and included in the contract can be details like what exceptions
an API raises. We don't necessarily need a standard to specify that (?)
but it is the sort of information that ought to be in docstrings where
relevant.
Michael
-Fred
--
http://www.ironpythoninaction.com/
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
