[Doc-SIG] epydoc reST markup for stdlib docstrings
goodger at python.org
Wed Apr 14 02:55:53 CEST 2010
On Tue, Apr 13, 2010 at 17:12, Barry Warsaw <barry at python.org> 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:
> 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.
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>
More information about the Doc-SIG