[Doc-SIG] docstring grammar

[uche.ogbuji@fourthought.com]

> Proposed format for docstrings:
> 
>   The whitespace at the beginning of a docstring is ignored.
> 
>   Paragraphs are separated by one or more blank lines.
> 
>   For compatibility with Guido, IDLE and Pythonwin (and increasing the
>   likelihood that the proposal will be accepted by GvR), the
>   docstrings of callables must follow the following convention
>   established in Python's builtins:
> 
>        >>> print len.__doc__
>        len(object) -> integer
> 
>        Return the number of items of a sequence or mapping.

The only thing I'd _maybe_ suggest in order to allow some structure is to 
eliminate the non-keyword sections:

        >>> print len.__doc__
        sig:: len(object) -> integer
 
        desc:: Return the number of items of a sequence or mapping.

I know this loses a bit from the point of view of the user's readability, but 
it would provide some structure which increases the author's flexibility, and 
makes conversion to "library format" easier.

Otherwise, your proposal seems a good start.

> Miscellaneous Thoughts:
> 
>   I chose double-colon notation for keywords so that one can have text
>   paragraphs which match the 'word:' notation without having them be
>   interpreted as keywords.

There are other conventions that would work, but '::' is as good as any.

>   Does this proposal make docstrings whitespace-heavy -- the
>   requirement to break each paragraph with a line of whitespace
>   means that a lot of lines are blank, especially when doing
>   'bulleted lists'

I would suggest dropping the requirement, which can be done if everything is 
keyword-modified.

>   The above was (quickly) written with parsing in mind.  Is it really
>   easily parseable?  If not, what needs to be changed so that it is
>   parseable?

I see no major parsing problems.  Bullets might be a bit of a bore, but 
nothing to kill progress.

>   Are there normal uses in docstrings where one wants to turn off the
>   automatic link detection?

I think we can come up with a basic escaping mechanism for this.  Maybe by 
preceding not-to-be-processed URLs and link keywords with '!'.

>   Is there value in having string interpolation?  David Arnold mentioned
> 
>        __version__ = "$Revision$[11:-2]
>        __date__ = "$Date$

I'd say leave this to a later version.

> PS: It goes without saying that while I railed against design by
> committee, I am of course hopeful for feedback, for technical reasons
> (dummy, you forgot special cases X, Y and Z!) and because I realize that a
> standards proposal needs at least broad agreement if not consensus to be
> effective in the long run.  The sharper-eyed will note that I stacked the
> deck in my favor in the above proposal by including what Guido does
> naturally as valid in the proposed grammar.

Damn the politics.  Full speed ahead.

-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org