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