[Doc-SIG] epydoc reST markup for stdlib docstrings

[Michael Foord]

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/