blob: f6ec09ebd5459f67bf002f2179b52cee2689c051 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
|
=====================
Docstring Semantics
=====================
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision$
:Date: $Date$
These are notes for a possible future PEP providing the final piece of
the Python docstring puzzle.
PythonDoc
=========
A Python version of the JavaDoc semantics (not syntax). A set of
conventions which are understood by the Docutils.
- 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
- Use field lists or definition lists for "tagged blocks".
- Frederic Giacometti's "iPhrase Python documentation conventions" is
an attachment to his Doc-SIG post of 2001-05-30
(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:
|
