forked from python/peps
-
Notifications
You must be signed in to change notification settings - Fork 0
/
pep-0216.txt
168 lines (118 loc) · 5.3 KB
/
pep-0216.txt
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
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
PEP: 216
Title: Docstring Format
Version: $Revision$
Last-Modified: $Date$
Author: moshez@zadka.site.co.il (Moshe Zadka)
Status: Rejected
Type: Informational
Content-Type: text/x-rst
Created: 31-Jul-2000
Post-History:
Superseded-By: 287
Notice
======
This PEP is rejected by the author. It has been superseded by PEP
287.
Abstract
========
Named Python objects, such as modules, classes and functions, have a
string attribute called ``__doc__``. If the first expression inside
the definition is a literal string, that string is assigned
to the ``__doc__`` attribute.
The ``__doc__`` attribute is called a documentation string, or docstring.
It is often used to summarize the interface of the module, class or
function. However, since there is no common format for documentation
string, tools for extracting docstrings and transforming those into
documentation in a standard format (e.g., DocBook) have not sprang
up in abundance, and those that do exist are for the most part
unmaintained and unused.
Perl Documentation
==================
In Perl, most modules are documented in a format called POD -- Plain
Old Documentation. This is an easy-to-type, very low level format
which integrates well with the Perl parser. Many tools exist to turn
POD documentation into other formats: info, HTML and man pages, among
others. However, in Perl, the information is not available at run-time.
Java Documentation
==================
In Java, special comments before classes and functions function to
document the code. A program to extract these, and turn them into
HTML documentation is called javadoc, and is part of the standard
Java distribution. However, the only output format that is supported
is HTML, and JavaDoc has a very intimate relationship with HTML.
Python Docstring Goals
======================
Python documentation string are easy to spot during parsing, and are
also available to the runtime interpreter. This double purpose is
a bit problematic, sometimes: for example, some are reluctant to have
too long docstrings, because they do not want to take much space in
the runtime. In addition, because of the current lack of tools, people
read objects' docstrings by "print"ing them, so a tendency to make them
brief and free of markups has sprung up. This tendency hinders writing
better documentation-extraction tools, since it causes docstrings to
contain little information, which is hard to parse.
High Level Solutions
====================
To counter the objection that the strings take up place in the running
program, it is suggested that documentation extraction tools will
concatenate a maximum prefix of string literals which appear in the
beginning of a definition. The first of these will also be available
in the interactive interpreter, so it should contain a few summary
lines.
Docstring Format Goals
======================
These are the goals for the docstring format, as discussed ad nauseam
in the doc-sig.
1. It must be easy to type with any standard text editor.
2. It must be readable to the casual observer.
3. It must not contain information which can be deduced from parsing
the module.
4. It must contain sufficient information so it can be converted
to any reasonable markup format.
5. It must be possible to write a module's entire documentation in
docstrings, without feeling hampered by the markup language.
Docstring Contents
==================
For requirement 5. above, it is needed to specify what must be
in docstrings.
At least the following must be available:
a. A tag that means "this is a Python *something*, guess what"
Example: In the sentence "The POP3 class", we need to markup "POP3"
so. The parser will be able to guess it is a class from the contents
of the ``poplib`` module, but we need to make it guess.
b. Tags that mean "this is a Python class/module/class var/instance var..."
Example: The usual Python idiom for singleton class ``A`` is to have ``_A``
as the class, and ``A`` a function which returns ``_A`` objects. It's usual
to document the class, nonetheless, as being ``A``. This requires the
strength to say "The class ``A``" and have ``A`` hyperlinked and marked-up
as a class.
c. An easy way to include Python source code/Python interactive sessions
d. Emphasis/bold
e. List/tables
Docstring Basic Structure
=========================
The documentation strings will be in StructuredTextNG
(http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG)
Since StructuredText is not yet strong enough to handle (a) and (b)
above, we will need to extend it. I suggest using
``[<optional description>:python identifier]``.
E.g.: ``[class:POP3]``, ``[:POP3.list]``, etc. If the description is missing,
a guess will be made from the text.
Unresolved Issues
=================
Is there a way to escape characters in ST? If so, how?
(example: * at the beginning of a line without being bullet symbol)
Is my suggestion above for Python symbols compatible with ST-NG?
How hard would it be to extend ST-NG to support it?
How do we describe input and output types of functions?
What additional constraint do we enforce on each docstring?
(module/class/function)?
What are the guesser rules?
Rejected Suggestions
====================
XML -- it's very hard to type, and too cluttered to read it comfortably.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: