On Apr 14, 2010, at 02:44 PM, Michael Foord wrote: >I'm not aware of other formats beyond epydoc and javadoc (I agree with >your opinion on javadoc) - oh and the .NET xml format which I strongly >recommend we steer clear of. Do you have any references?
XML is not human readable or writable (IMNSHO :). As far as epydoc, this is probably the only page you care about: http://epydoc.sourceforge.net/manual-fields.html It describes the fields that are used to describe parameters, return types, and exceptions. Note that while the body of that page uses "Epytext" format, the table near the top of the page shows the three alternative syntaxes. Of those of course I recommend reST (the middle column). You have to mentally translate the syntax in the body of the page to reST though. Keep in mind too that it's not always necessary to include *every* field in a function's docstring. Obviously, include only what is useful to the consumer of the function's documentation. For example, when it's completely obvious, or when I actually don't know (e.g. because the method proxies some other method 3 levels deep), I might not include the :type: field. I also won't include obvious, common exceptions. I do think *that* can be left to the author's taste. Here's an example: def inject_message(mlist, msg, recips=None, switchboard=None, **kws): """Inject a message into a queue. :param mlist: The mailing list this message is destined for. :type mlist: `IMailingList` :param msg: The message object to inject. :type msg: `email.message.Message` or derived :param recips: Optional set of recipients to put into the message's metadata. :type recips: sequence of strings :param switchboard: Optional name of switchboard to inject this message into. If not given, the 'in' switchboard is used. :type switchboard: string :param kws: Additional values for the message metadata. :type kws: dictionary """ Note that :param: values are complete sentences, while :type: values are informative types, not necessarily explicit types (e.g. an interface for mlist and 'string' instead of 'str' or 'unicode' for switchboard). This function doesn't return anything and doesn't explicitly raise any exceptions. The implicit KeyErrors that could be raised are not described. >I don't recall *ever* seeing a consistent pattern for specifying >parameters and return values in Python docstrings. Exactly. :) >I too would prefer a consistent pattern be adopted for the Python >standard library. Good luck finding someone to go and change all the >docstrings in the standard library to use it... Like all other coding standards we have for the stdlib, the migration can happen opportunistically over time. But folks need a target or nothing will ever happen. -Barry
signature.asc
Description: PGP signature
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
