Re: epydoc reST markup for stdlib docstrings
David Goodger <[email protected]>
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Message-ID | <[email protected]> |
On Tue, Apr 13, 2010 at 17:12, Barry Warsaw <[email protected]> wrote: > During some recent work on the PEP 3147, I had a need to add some > documentation (docstrings) to some new functions. To document the function > arguments I added epydoc reST style markup: > > def ensure_bytecode_path(bytecode_path): > """Ensure that the __pycache__ directory for PEP 3147 pyc file exists. > > :param bytecode_path: File system path to PEP 3147 pyc file. > """ > > Now, I didn't even think twice about this because several of the larger Python > projects I work on have already adopted epydoc reST markup for API. During > his review, Antoine disapproved of this, pointing to PEPs 257 and 287. My > reading of these PEPs however, certainly doesn't prohibit the use of epydoc > reST markup. PEP 257 doesn't address docstring syntax at all, just conventions. PEP 287 addresses "only the low-level syntax of docstrings". IOW, these PEPs don't apply to Antoine's concern. High-level semantics simply aren't addressed by them. (As the author or co-author, I should know :-) I once wrote up some notes about docstring semantics: http://docutils.sourceforge.net/docs/dev/semantics.html > Georg and I pointed to the lack of a clear, consistent convention > in the Python stdlib. I would like to propose that epydoc reST markup be made > that convention. > > http://epydoc.sourceforge.net/epydoc.html#epydoc-fields I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to making the epydoc field conventions *a* standard convention, allowing for others. Just as choice of markup is very much a matter of personal preference (some people *love* dealing with XML directly), choice of API documentation semantics is also a personal preference thing. We would be wise to allow for choice. -- David Goodger <http://python.net/~goodger> _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig