5
:Contact: goodger@users.sourceforge.net
6
:Revision: $Revision: 1.4 $
7
:Date: $Date: 2003/06/09 21:26:30 $
8
:Copyright: This document has been placed in the public domain.
10
These are notes for a possible future PEP providing the final piece of
11
the Python docstring puzzle: docstring semantics or documentation
12
methodology. `PEP 257`_, Docstring Conventions, sketches out some
13
guidelines, but does not get into methodology details.
15
I haven't explored documentation methodology more because, in my
16
opinion, it is a completely separate issue from syntax, and it's even
17
more controversial than syntax. Nobody wants to be told how to lay
18
out their documentation, a la JavaDoc_. I think the JavaDoc way is
19
butt-ugly, but it *is* an established standard for the Java world.
20
Any standard documentation methodology has to be formal enough to be
21
useful but remain light enough to be usable. If the methodology is
22
too strict, too heavy, or too ugly, many/most will not want to use it.
24
I think a standard methodology could benefit the Python community, but
25
it would be a hard sell. A PEP would be the place to start. For most
26
human-readable documentation needs, the free-form text approach is
27
adequate. We'd only need a formal methodology if we want to extract
28
the parameters into a data dictionary, index, or summary of some kind.
34
(Not to be confused with Daniel Larsson's pythondoc_ project.)
36
A Python version of the JavaDoc_ semantics (not syntax). A set of
37
conventions which are understood by the Docutils. What JavaDoc has
38
done is to establish a syntax that enables a certain documentation
39
methodology, or standard *semantics*. JavaDoc is not just syntax; it
40
prescribes a methodology.
42
- Use field lists or definition lists for "tagged blocks". By this I
43
mean that field lists can be used similarly to JavaDoc's ``@tag``
44
syntax. That's actually one of the motivators behind field lists.
45
For example, we could have::
49
- `lines`: a list of one-line strings without newlines.
50
- `until_blank`: Stop collecting at the first blank line if
52
- `strip_indent`: Strip common leading indent if true (1,
56
- a list of indented lines with mininum indent removed;
57
- the amount of the indent;
58
- whether or not the block finished with a blank line or at
62
This is taken straight out of docutils/statemachine.py, in which I
63
experimented with a simple documentation methodology. Another
64
variation I've thought of exploits the Grouch_-compatible
65
"classifier" element of definition lists. For example::
69
List of one-line strings without newlines.
70
`until_blank` : boolean
71
Stop collecting at the first blank line if true (1).
72
`strip_indent` : boolean
73
Strip common leading indent if true (1, default).
75
- Field lists could even be used in a one-to-one correspondence with
76
JavaDoc ``@tags``, although I doubt if I'd recommend it. Several
77
ports of JavaDoc's ``@tag`` methodology exist in Python, most
78
recently Ed Loper's "epydoc_".
84
- Can we extract comments from parsed modules? Could be handy for
85
documenting function/method parameters::
88
source, # path of input file
89
dest # path of output file
92
This would save having to repeat parameter names in the docstring.
94
Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG]
97
it would be quite hard to add a new param to this method without
98
realising you should document it
100
- Frederic Giacometti's `iPhrase Python documentation conventions`_ is
101
an attachment to his Doc-SIG post of 2001-05-30.
104
.. _PEP 257: http://www.python.org/peps/pep-0257.html
105
.. _JavaDoc: http://java.sun.com/j2se/javadoc/
106
.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
107
.. _Grouch: http://www.mems-exchange.org/software/grouch/
108
.. _epydoc: http://epydoc.sf.net/
109
.. _iPhrase Python documentation conventions:
110
http://mail.python.org/pipermail/doc-sig/2001-May/001840.html
116
indent-tabs-mode: nil
117
sentence-end-double-space: t
added
removed
spec/semantics.txt
