[Doc-SIG] docstring grammar

Edward Welbourne Edward Welbourne <eddyw@lsl.co.uk>
Mon, 29 Nov 1999 17:46:32 +0000

Manuel: if David includes `Keyword::' in his bits and pieces, would

     data retrieval

(within a doc-string) contain the information you've been wanting to
take out of your


etc. (with apologies for not having followed your system well enough to
mimic the names you'd actually use) ?  What I've understood of your
scheme appears to tell me the answer Yes.  If so, I guess you could just
slurp the Keyword slice out of a namespace-tree generated from
doc-strings and, I suspect, happiness would abound and confusion abate.

I know you have bits that define an indexing command that expands to
several indexing commands, which this lacks: but could the same effect
be arrived at by turning your set of indexing command definitions into
an `expert system' that expands some keywords ?

And ... to folk who know about the state of the craft of indexing: is
there a better way to go with this ?  After all, I'm pretty much just
borrowing from one of HTML's META tags here ...

Now, back to the spec itself:

> For compatibility with Guido, IDLE ... 
>        len(object) -> integer

docstring-startline: archetypical-call [ '->' return ] ['--' summary ]

Quite apart from compatibility - this is a *good* approach.
I guess that could be why Guido does it ...

>  Each paragraph is either 'text' or a 'keyword-tagged block'.  
Sounds good.  Flesh and skeleton.

I'm with Tibs on the #-comment stuff - particularly the liberty to
simply embed a piece of python code in a doc string.

>   A 'keyword-tagged block' is nested much like Python code.
Yes, thank you very much, beautiful - this will give us scope for nested
sub-structures in the keyword-tagged data: in particular, get rid of
that Date_of_release ... use

Author:: David Ascher
    Date:: 1999/11/28
    Name:: post-gendoc-0.1
    Stability:: draft

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 (and, of course, it isn't the
only word to worry about).  (The flip-side is: I can see myself getting
irritated by the need to say Example:: as a keyword immediately after
I've ended a paragraph with the word example ...)

Note: this keyword representation is isomorphic to XML via `the usual'
equivalences between (pythonic) indentation-structuring and the
begin-end style of structuring that C and XML use.

keyword: single-liner

keyword: indent block dedent
block (possibly transformed down a bit itself)

>     Some keywords can have special parsing rules, 
coo, context-sensitive parsing ;^)
Good idea.  Lets some things only be keywords where they need to be ...

>   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?
Well, the bulleting (and descriptive list stuff) has been explored
already in pythondoc / gendoc, so clearly it's all `within scope'.
Heh.  And between David and Tibs, surely we have the parsing technology ...

On the subject of vertical space ... I'd guess the parser won't need a
blank line between 
    * the end of a paragraph and

    * the start of its first indented subordinate ?

Though, indeed, I do want to take out the other blank line here, and I
thought gendoc managed that ...

>   Is there value in having string interpolation?
Yes.  Definitely.
I hadn't realised it was possible until you mentioned it, now I'm sure
it's Needed.

> Hopefully constructively, 
having had some time to think on it, I'd say Thoroughly so.

Hierarchical namespaces,
Context-sensitive parsing,
Mappable to XML but written like python,
Scope for indexing, and for arbitrary extension within sub-namespaces,
Conformance to the only important standard (Guido's de facto habits ;^)
Proposed by someone who knows how to write parsers ...
No need for the run-time system to bother with any of it
	(all hidden inside the doc string)

Thank you David,

PS - David: you do realise, though, that the committee won't keep up the
momentum on this unless you ruthlessly play Gdo until he joins in ...