[Doc-SIG] Re: docstring signatures

Guido van Rossum guido@digicool.com
Sat, 24 Mar 2001 15:37:52 -0500


> > PS.  Don't spend too much time trying to make StructuredText or some
> > variation thereof work.  In my experience with systems that use ST
> > (like ZWiki), it sucks.  There basically are two options I like:
> > nicely laid out plain text, or a real markup language like Latex or
> > DocBook.
> 
> Unfortunately, it's a bit late for that (there's been a lot of work
> this month put into trying to get a ST variant to work).  I don't 
> mind not using ST, but before we start working on other formatting
> conventions, I thought I should get a better idea of what you would
> or would not like, so we don't end up spending another month on
> something you won't like. ;)
> 
> Here's the abstract from the PEP I've been putting together.  It
> should give you a good idea of what we're trying to accomplish, at
> least:
> 
>     Python documentation strings provide a convenient way of
>     associating documentation with many types of Python objects.
>     However, there are currently no widespread conventions for how the
>     information in documentation strings should be formatted.

Not true.  Most of the standard library uses the same convention, and
even if it's not quite written down, it wouldn't be hard to figure out
what it is.  Also, my Python Style Guide
(http://www.python.org/doc/essays/styleguide.html) has quite a bit of
guidance.

>     As a
>     result, it is very difficult to write widely-applicable tools for
>     processing documentation strings.

Again not true.  Ping's pydoc does quite well second-guessing the
existing conventions.

>     Such tools would be useful for
>     a variety of tasks, such as:
> 
>         * Converting documentation to HTML, LaTeX, or other formats.
>         * Browsing documentation within python.
>         * Ensuring that documentation meets specific requirements.
> 
>     This PEP proposes that the Python community adopt a well-defined
>     set of conventions for writing "formatted documentation strings."
>     These conventions can then be relied upon when writing tools to
>     process formatted documentation strings.
> 
>     Note that some Python programs may choose not to use formatted
>     documentation strings.  For example, programs like Zope [1] have
>     used documentation strings for purposes other than strict
>     documentation, and it would be inappropriate to expect them to
>     change how they use documentation strings.  Also, some programmers
>     may prefer to write plaintext documentation strings.

Zope's a red herring (they are trying to get away from this Bobo-ism).
Very often we read docstrings as part of the source code, and there
plaintext is best, given the state of the art in text editors.

> Also, here are the "design goals" I defined:
> 
>     The following goals guided this PEP's design of conventions for
>     writing formatted documentation strings.
> 
>         * Intuitiveness: The meaning of a well-formed formatted
>           documentation string should be obvious to a reader, even if
>           that reader is not familiar with the formatting conventions.
> 
>         * Ease of use: If the formatting conventions are to be
>           accepted by the Python community, then it must be easy to
>           write formatted documentation strings.

Of course.  This is all apple pie and motherhood.  nobody will want
documentation that's unintuitive or hard to use!

>         * Formality: The formatting conventions must be formally
>           specified.  A formal specification allows different tools to
>           interpret formatted documentation strings consistantly, and
>           allows for "competing, interoperable implementations," as
>           specified in PEP 1 [5].  

Yes, this is important.  But when we choose plaintext, we don't need
much of a formal specification!

>         * Expressive Power: The formatting conventions must have
>           enough expressive power to allow users to write the API
>           documentation for any python object.

I've never found that plaintext got in the way of my expressiveness.

>     The following "secondary design goals" follow directly from the
>     primary design goals, but are important enough to deserve separate 
>     mention:
> 
>         * Simplicity: The formatting conventions should be as simple
>           as is practical, and there should be minimal interaction
>           between different aspects of the formatting conventions.
>           This goal derives from intuitiveness and ease of use.

More motherhood.

>         * Safety: No well-formed formatted documentation string should 
>           result in unexpected formatting.  This goal derives from
>           intuitiveness.

This is a good one.  ST loses big here!

> So the question then is what sort of markup language we should define.
> I'd be quite happy to use something like Javadoc uses (but with a more
> restricted set of acceptable XML elements), but other people think
> that it's too hard to read/write...

I though Javadoc was geared too much towards generating HTML; we
should not focus too much on HTML.

> I'm also curious why you don't like ST-like markups.  We've been
> putting a fair amount of work into formalizing it & making sure it's
> "safe" (e.g., it's an error to say *x**b*c**d*).  If we can
> successfully do both, would that alleviate some of your concerns
> about ST? 

The proponents of ST (that I've talked to) seem to believe that it's
unnecessary to tell the users what the exact rules are.  This, plus
numerous bugs in the ST implementation and the context in which it is
used, continuously bite me.  E.g. if a paragraph starts with a word
followed by a period, the word is replaced with "1.".  If I use "--"
anywhere in the first line of a paragraph it is turned into a
<DT>...<DD>... style construct.  There's no easy way to escape HTML
keywords.  In general, when you *don't* want something to have its
special effect, there's no way to escape it.  There's no way that I
know of to create a bulleted item consisting of several paragraphs.
The reliance on indentation levels to detect various levels of
headings never works for me.

> Any info you can give on what you would like to see come out 
> of this project (or pointers to info) would be most appreciated.

A lot of effort has gone into creating a body of documentation for the
standard library *outside* the source code.  It is rich in mark-up,
indexed, contains many examples, well maintained, and is generally
considered high quality documentation.  I don't want to have to redo
the work that went into creating this.

It should be easier to combine code and documentation for 3rd party
modules, and there should be an easier way to integrate such
documentation into (a version of) the standard documentation.  But I
disagree with the viewpoint that documentation should be maintained in
the same file as source code.  (If you believe the argument that it
is easier to ensure that it stays up to date, think again.  This never
worked for comments.)

--Guido van Rossum (home page: http://www.python.org/~guido/)