On Tue, Apr 13, 2010 at 17:12, Barry Warsaw <barry@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.
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>