[Doc-SIG] docstring grammar

[David Ascher]

Mark Hammond:

> Thus: * Any line starting with a word followed by a colon can be
> considered a keyword.  If you dont want this, just make sure its not
> the first word on the line.

I agree with Edward on this one -- this is too fragile.

I consider the whitespace issue to be real only in the context of lists,
and I think that gendoc has shown that it's solvable within the context of
lists.  I stand by the keyword notation I presented:  either

   Keyword:
     text block
     spanning one or more lines 

or

   Keyword: one-line block

as long as they are both in separate paragraphs.

> Not sure if this is already somewhere in the proposal, but
> I would like to see '--' as indicator of a single line
> text block. This would be useful in vertically compressing
> the docstrings somewhat (and it already being used in the
> signature line for such a purpose).

Isn't that just redundant with the : notation?  Note that I don't mind a
little redundancy, but it's unpythonic.  

> > > * A star or dash starting a line can be considered a new list item.
> > > Again, if it is truly a hyphen or whatever else, just adjust your line
> > > wrap slightly so it is no longer the first word.
> > 
> > Alternatively, all lists use the same `item-introducer' character and
> > follow it with an optional character indicating what bullet to use.
> > Thus one might have (taking ~ as the introducer for the illustration)
> > 
> > ...
> 
> Let's leave this to some list parser (are we starting to head
> for NP-completeness again ;-).

Absolutely!

Mark:
> Other random thoughts:
> * The [blah] notation is good, but needs to be well defined.  eg,

MAL:

> Right. It should ideally perform the same lookup as Python would
> in the global namespace. The resulting object could then either
> be handled recursively by the doc tool or simply stored by reference
> for later use (e.g. via the file name of a module or the id of an
> object).

Edward:
> The thing that saves [this] from being problematic is that the format in
> which it was introduced presumed that one was going to use a brief
> mnemonic as [this] word and end the docstring with a chunk which
> explains the cross-references (new keyword: Xrefs ?) 

I think that both are needed.  I believe that the namespaces looked up
should be:
  1) the local namespace of the docstring -- i.e., the set of keywords
     defined in the "References" keyword block in the current docstring.
  2) the global namespace of the docstrings -- i.e. the set of keywords 
     defined in the "References" keyword block in the MODULE docstring.
  3) The global Python namespace for that module
  4) Some namespace corresponding to builtins & unimported modules, yet
     ill-defined.

The point of 2) is that I often want to introduce references that I use in
a given module at the level of a docstring, but then want to refer to
those documents in specific function docstrings.

(Good thing we don't have to worry about garbage collection with these
circular references =)

> Since [] is only used for lists in Python, we could
> define the RE '\[[a-zA-Z0-9_.]+\]' for our purposes and
> raise an exception in case the enclosed reference cannot
> be mapped to a symbol in the global namespace (note: no
> whitespace, no commas) which either evaluates to a function,
> method, module or reference object.
> 
> Doc strings like "...use [None]*10 as argument..." will fail,
> but are easily avoided by inserting some extra whitespace, e.g.
> "...use [ None ] * 10 as argument...".

I like that bit, especially since the 'complete' tagging of that example
would wrap [None]*10 in whatever inline code markup is chosen.

--david