99 lines
3.8 KiB
Plaintext
99 lines
3.8 KiB
Plaintext
PEP: 216
|
||
Title: Docstring Format
|
||
Version: $Revision$
|
||
Author: moshez@math.huji.ac.il (Moshe Zadka)
|
||
Status: Draft
|
||
Type: Informational
|
||
Created: 31-Jul-2000
|
||
|
||
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 tendancy to make them
|
||
brief and free of markups has sprung up. This tendancy 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 neasum
|
||
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"
|
||
b. Tags that mean "this is a Python class/module/class var/instance var..."
|
||
c. An easy way to include Python source code/Python interactive sessions
|
||
d. Emphasis/bold
|
||
e. List/tables
|
||
|
||
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:
|