Re: epydoc reST markup for stdlib docstrings
Fred Drake <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
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. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Mille _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig