[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
r"^\s*Example:\s*"
The code support will consist almost entirely of changing the regexp to
r"\s*(Example:|>>>)\s*"
Not trivial, but as easy as it could be and stay this side of trivial
<wink>.
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
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
wasteful.
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.
if-swaying-isn't-effective-next-it's-pouting-and-then-on-to-
threats<wink>-ly y'rs - tim