[Doc-SIG] docstring grammar

[David Ascher]

On Mon, 29 Nov 1999, M.-A. Lemburg wrote:

> How would the following be handled:
> 
> Arguments: file -- a file like object
> 	   mode -- file mode indicator as defined in [__builtin__.open]

That, btw, is illegal -- the block must either be a single-line block or
an indented block.

> 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:

Agreed -- I made a similar point in another email which waved 'hi!' to
yours as they crossed somewhere over the atlantic. =)

> 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

Depends on the case.  In a long docstring, one might want to have several
sections, each with Examples: subsections.

I propose that part of the definition of a keyword is (along with any
special parsing rules) whether it can be duplicated in a docstring.

--david