[Doc-SIG] docstring grammar

Tim Peters tim_one@email.msn.com
Wed, 1 Dec 1999 03:15:06 -0500

[David Ascher]
> The only question I suppose is whether one should require a keyword (Test:
> or other) to keep the top-level syntax trivial, or special-case the
> recognition of >>>-beginning paragraphs.
> I'm leaning for the former, as it can evolve to the latter if there is
> sufficient call for it from the user base, and I think it does keep the
> code simpler.  But I'm willing to be swayed.

Parsing is never trivial, although it can be made *easy*, and you're already
e.g. special-casing the snot out of the first line of the docstring (unless,
as someone else recently and regrettably <0.3 wink> suggested, you split
that into keyword-introduced "Signature:" and "Summary:" paragraphs).

You're going to have *some* way to spell "what follows is an unstructured
code block up until the next empty line or end-of-docstring".  You'll end up
recognizing that with a regexp, like


The code support will consist almost entirely of changing the regexp to


Not trivial, but as easy as it could be and stay this side of trivial

Here's the start of a very long module docstring:

Rat objects support exact, unbounded rational arithmetic.

Skip to MODULE SUMMARY at the end for the short story.

Rat objects also support rounding and formating methods sufficient
to emulate floating-point arithmetic in your choice of base, number
of significant digits, and rounding discipline.

>>> from Rational.Rat import Rat  # Rat constructor
>>> from Rational import Format   # used later
>>> print Rat() # no args gets 0

Construct a Rat from an int, long, float, or string representing a
rational or float:

>>> print Rat(5), Rat(5L), Rat(5.0), Rat("5"), Rat("50e-1")
5 5 5 5 5

Or you can pass two ints or longs, to construct their ratio.  The
denominator must be >= 1:

>>> print Rat(5, 1), Rat(1, 5), Rat("1/5"), Rat("10/1010_2")
5 1/5 1/5 1/5

The "_2" at the end of the last one there is a "base tag", and says
"10/1010" is to be interpreted as a ratio in binary notation.
Any int base >= 2 can be used.

etc etc etc

There are dozens of example code blocks in this docstring.  Indenting them
all and tagging them with redundant "Example:" labels would be both ugly and

I *love* the thrust of the new proposals here because, frankly, I'm likely
never to run a docstring thru any sort of docstring processor (except
perhaps to extract the first line), and the current proposals have a nice
WYSIWYG flavor.  When a *Python* programmer sees ">>>", they know exactly
what they're about to get.

    threats<wink>-ly y'rs  - tim