Re: epydoc reST markup for stdlib docstrings
Michael Foord <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
On 14/04/2010 16:37, Fred Drake wrote: > On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan<[email protected]> 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 - [email protected] http://mail.python.org/mailman/listinfo/doc-sig