[Doc-SIG] epydoc reST markup for stdlib docstrings
Michael Foord
fuzzyman at voidspace.org.uk
Wed Apr 14 16:39:20 CEST 2010
On 14/04/2010 16:37, Fred Drake wrote:
> 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.
>
>
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/
More information about the Doc-SIG
mailing list