|
|
===================== |
|
|
Docstring Semantics |
|
|
===================== |
|
|
:Author: David Goodger |
|
|
:Contact: docutils-develop@lists.sourceforge.net |
|
|
:Revision: $Revision: 7302 $ |
|
|
:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $ |
|
|
: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. |
|
|
|
|
|
- Use field lists or definition lists for "tagged blocks". By this I |
|
|
mean that field lists can be used similarly to JavaDoc's ``@tag`` |
|
|
syntax. That's actually one of the motivators behind field lists. |
|
|
For example, we could have:: |
|
|
|
|
|
""" |
|
|
:Parameters: |
|
|
- `lines`: a list of one-line strings without newlines. |
|
|
- `until_blank`: Stop collecting at the first blank line if |
|
|
true (1). |
|
|
- `strip_indent`: Strip common leading indent if true (1, |
|
|
default). |
|
|
|
|
|
:Return: |
|
|
- a list of indented lines with mininum indent removed; |
|
|
- the amount of the indent; |
|
|
- whether or not the block finished with a blank line or at |
|
|
the end of `lines`. |
|
|
""" |
|
|
|
|
|
This is taken straight out of docutils/statemachine.py, in which I |
|
|
experimented with a simple documentation methodology. Another |
|
|
variation I've thought of exploits the Grouch_-compatible |
|
|
"classifier" element of definition lists. For example:: |
|
|
|
|
|
:Parameters: |
|
|
`lines` : [string] |
|
|
List of one-line strings without newlines. |
|
|
`until_blank` : boolean |
|
|
Stop collecting at the first blank line if true (1). |
|
|
`strip_indent` : boolean |
|
|
Strip common leading indent if true (1, default). |
|
|
|
|
|
- Field lists could even be used in a one-to-one correspondence with |
|
|
JavaDoc ``@tags``, although I doubt if I'd recommend it. Several |
|
|
ports of JavaDoc's ``@tag`` methodology exist in Python, most |
|
|
recently Ed Loper's "epydoc_". |
|
|
|
|
|
|
|
|
Other Ideas |
|
|
=========== |
|
|
|
|
|
- Can we extract comments from parsed modules? Could be handy for |
|
|
documenting function/method parameters:: |
|
|
|
|
|
def method(self, |
|
|
source, # path of input file |
|
|
dest # path of output file |
|
|
): |
|
|
|
|
|
This would save having to repeat parameter names in the docstring. |
|
|
|
|
|
Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG] |
|
|
Documentation tool": |
|
|
|
|
|
it would be quite hard to add a new param to this method without |
|
|
realising you should document it |
|
|
|
|
|
- Frederic Giacometti's `iPhrase Python documentation conventions`_ is |
|
|
an attachment to his Doc-SIG post of 2001-05-30. |
|
|
|
|
|
|
|
|
.. _PEP 257: http://www.python.org/peps/pep-0257.html |
|
|
.. _JavaDoc: http://java.sun.com/j2se/javadoc/ |
|
|
.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ |
|
|
.. _Grouch: http://www.mems-exchange.org/software/grouch/ |
|
|
.. _epydoc: http://epydoc.sf.net/ |
|
|
.. _iPhrase Python documentation conventions: |
|
|
http://mail.python.org/pipermail/doc-sig/2001-May/001840.html |
|
|
|
|
|
|
|
|
.. |
|
|
Local Variables: |
|
|
mode: indented-text |
|
|
indent-tabs-mode: nil |
|
|
sentence-end-double-space: t |
|
|
fill-column: 70 |
|
|
End:
|
|
|
|
