[Doc-SIG] epydoc reST markup for stdlib docstrings

[David Goodger]

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:
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>