Abstract

Named Python objects, such as modules, classes and functions, have astring attribute called__doc__. If the first expression insidethe definition is a literal string, that string is assignedto 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 orfunction. However, since there is no common format for documentationstring, tools for extracting docstrings and transforming those intodocumentation in a standard format (e.g., DocBook) have not sprangup in abundance, and those that do exist are for the most partunmaintained and unused.

Perl Documentation

In Perl, most modules are documented in a format called POD – PlainOld Documentation. This is an easy-to-type, very low level formatwhich integrates well with the Perl parser. Many tools exist to turnPOD documentation into other formats: info, HTML and man pages, amongothers. However, in Perl, the information is not available at run-time.

Java Documentation

In Java, special comments before classes and functions function todocument the code. A program to extract these, and turn them intoHTML documentation is called javadoc, and is part of the standardJava distribution. However, the only output format that is supportedis HTML, and JavaDoc has a very intimate relationship with HTML.

Python Docstring Goals

Python documentation string are easy to spot during parsing, and arealso available to the runtime interpreter. This double purpose isa bit problematic, sometimes: for example, some are reluctant to havetoo long docstrings, because they do not want to take much space inthe runtime. In addition, because of the current lack of tools, peopleread objects’ docstrings by “print”ing them, so a tendency to make thembrief and free of markups has sprung up. This tendency hinders writingbetter documentation-extraction tools, since it causes docstrings tocontain little information, which is hard to parse.

High Level Solutions

To counter the objection that the strings take up place in the runningprogram, it is suggested that documentation extraction tools willconcatenate a maximum prefix of string literals which appear in thebeginning of a definition. The first of these will also be availablein the interactive interpreter, so it should contain a few summarylines.

Docstring Format Goals

These are the goals for the docstring format, as discussed ad nauseamin 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 parsingthe module.
4. It must contain sufficient information so it can be convertedto any reasonable markup format.
5. It must be possible to write a module’s entire documentation indocstrings, without feeling hampered by the markup language.

Docstring Contents

For requirement 5. above, it is needed to specify what must bein docstrings.

At least the following must be available:

1. A tag that means “this is a Pythonsomething, 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 contentsof thepoplib module, but we need to make it guess.

2. Tags that mean “this is a Python class/module/class var/instance var…”

   Example: The usual Python idiom for singleton classA is to have_Aas the class, andA a function which returns_A objects. It’s usualto document the class, nonetheless, as beingA. This requires thestrength to say “The classA” and haveA hyperlinked and marked-upas a class.

3. An easy way to include Python source code/Python interactive sessions
4. Emphasis/bold
5. 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[<optionaldescription>:pythonidentifier].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.