[Doc-SIG] docstring grammar

[M.-A. Lemburg]

David Ascher wrote:
> 
> > I was initially confused about : or :: because your examples began with
> > the first keyword I'd thought of, namely Example, and only used one :
> > with that one, going on to :: for the rest - then I noticed that you
> > weren't offering it as an example keyword but using it to introduce your
> > list of examples.  While I would far sooner have only one :, those of us
> > advocating this need to watch for the danger that the parser will get
> > similarly confused between the author's use of `Example:' in the manner
> > of English idiom and in its keyword sense.
> 
> After a little thought, I'm tempted to remove the :: requirement as well.
> In my proposal, I think that using the : after Example was a mistake in
> style.  If it was a heading then it should just be text w/o a colon. If it
> was supposed to be more of a sentence then it should have been spelled
> out, as in:
> 
>    For example, we can have:
> 
> The *intent* was, however, to avoid the 'danger' you note above.  I'm
> still open to go either way, "safe" or "comfortable".

I'd suggest using '^ *[a-zA-Z_]+[a-zA-Z_0-9]*: *' as RE for
keywords, i.e. keywords are Python identifiers immediatly followed
by a colon starting a line of a doc string. That should avoid
most complications, I guess.

	For example: blablablba
and
	...long sentence..., for
	example :

would not be parsed as keywords, while

	Example: a=1;b=2

does fit the above definition (I don't see a problem with including
examples in the parsed sections, BTW... examples are often much
more intuitive to understand than complex definitions).

Something else:

How would the following be handled:

Arguments: file -- a file like object
	   mode -- file mode indicator as defined in [__builtin__.open]
Arguments: buffersize -- optional buffer size in bytes

that is, what happens if a keyword appears twice ? In the above
case an error should be raised, but sometimes this may be
useful:

Example:
	first multi-line example

Example:
	second multi-line example

Hmm, perhaps these two examples should be wrapped using bullets:

Examples:
	- first example spanning multiple lines
	- second example

-- 
Marc-Andre Lemburg
______________________________________________________________________
Y2000:                                                    32 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/