Docstring Semantics

Author: David Goodger
Contact: docutils-develop@lists.sourceforge.net
Revision: 7302
Date: 2012-01-03
Copyright: This document has been placed in the public domain.

These are notes for a possible future PEP providing the final piece of the Python docstring puzzle: docstring semantics or documentation methodology. PEP 257, Docstring Conventions, sketches out some guidelines, but does not get into methodology details.

I haven't explored documentation methodology more because, in my opinion, it is a completely separate issue from syntax, and it's even more controversial than syntax. Nobody wants to be told how to lay out their documentation, a la JavaDoc. I think the JavaDoc way is butt-ugly, but it is an established standard for the Java world. Any standard documentation methodology has to be formal enough to be useful but remain light enough to be usable. If the methodology is too strict, too heavy, or too ugly, many/most will not want to use it.

I think a standard methodology could benefit the Python community, but it would be a hard sell. A PEP would be the place to start. For most human-readable documentation needs, the free-form text approach is adequate. We'd only need a formal methodology if we want to extract the parameters into a data dictionary, index, or summary of some kind.

PythonDoc

(Not to be confused with Daniel Larsson's pythondoc project.)

A Python version of the JavaDoc semantics (not syntax). A set of conventions which are understood by the Docutils. What JavaDoc has done is to establish a syntax that enables a certain documentation methodology, or standard semantics. JavaDoc is not just syntax; it prescribes a methodology.

Other Ideas