From: Ben F. <big...@be...> - 2008-09-24 07:51:32
|
"Sam Partington" <sam...@gm...> writes: > We wanted to have some markup to document the parameters and return > values to each of the functions, so I came up with the following > directive syntax. Rather than new directives (that, as you point out, cause problems when the directives are not defined), I've seen this problem addressed with reST field lists: one field per parameter, and one for the return value:: class Foo(object): """ A class to frobnicate zpatos. Represents a single Foo that can frobnicate arbitrary zpatos in a dwibeirous context. """ def frobnicate(zpato, spangulate=False): """ Frobnicate the specified zpato. Frobnicate the specified zpato in the context of this Foo, optionally spangulating. :param zpato: The zpato to frobnicate. Must be formatted as a glurpole. :param spangulate: If True, the frobnication is spangulated first. :return: The resulting frobnicated zpato. """ pass I've been using the above documentation style more and more in my code recently. It's PEP 254 compliant, reasonably succinct for the information content, and the doc strings are valid reST documents without any extra context. > Also, I like to imagine a day when all python modules are documented > using docutils, and there is a help tool (possibly hooked into an > editor) that reads them on the fly Hear hear. -- \ “Some forms of reality are so horrible we refuse to face them, | `\ unless we are trapped into it by comedy. To label any subject | _o__) unsuitable for comedy is to admit defeat.” —Peter Sellers | Ben Finney <be...@be...> |