[Doc-SIG] docstring grammar

[M.-A. Lemburg]

David Ascher wrote:
> 
> On Mon, 29 Nov 1999, M.-A. Lemburg wrote:
> 
> > This raises the question of whether to parse or evaluate the
> > loaded module. Evaluation has the benefit of providing "automatic"
> > context, i.e. the symbols defined in the global namespace
> > are exactly the ones relevant for class definitions, etc. It
> > probably makes contruction of interdepence graphs a lot easier
> > to write. On the downside you have unwanted side effects due to
> > loading different modules.
> 
> Good point. Too many modules "do things" on import, some exceedingly
> expensive. I have written modules where the import never ends, by design
> =).  I'm afraid that parsing is all we can do safely with the Python code.
> That does make interpolation much more delicate.  Maybe we can do
> everything but string interpolation w/ parsing, and then defer string
> interpolation until and if the module can be evaluated safely.  Somehow
> we'd need to indicate to the docstring processor whether that evaluation
> is safe or not.

I think gendoc did this with a command line switch... well the
early versions did (I think under a different name though, or
perhaps the name is different now ?).
 
> > Some notes on the proposal:
> >
> > · Mentioning the function/method signature is ok, but sometimes
> >   not needed since e.g. the byte code has enough information to
> >   deduce the signature from it. This is not true for builtin
> >   function which is probably the reason for all builtin doc
> >   strings to include the signature.
> 
> Right.  It's not true for builtins, extension module functions, and I'm
> not sure how easy it is for JPython code.  I have no problem with somehow
> making it easy to omit those in cases where the information can be
> obtained through the bytecode.

There's code in hack.py for the extraction and also a more
generic module by Fredrik Lundh for building signature strings.

> > · I would extend the reference scheme to a lookup in the module
> >   globals in case the local one (in the Reference section) fails.
> >   You could then write e.g. "For details see the [string] module."
> >   and the doc tool would then generate some hyperlink to the
> >   string module provided the string module is loaded into the
> >   global namespace.
> 
> Sounds good to me!

Without too much parsing overhead this only works for
the evaluation technique though. Would be nice to have...
even if it doesn't work for some reason (the doc tool could
then just produce some different markup for the reference
string, e.g. put it in italics).
 
> > · Standard symbols like __version__ could be included and used
> >   by the doc tool per default without the user specifying
> >   any special "Version:: %(__version__)s" % globals() tags.
> 
> Fine.  I think that falls somewhat outside of the 'docstring' proposal,
> but I agree with it.

True. It's something I've added to my hack.py formatting
functions and I thought it would be nice to have... (it also
encourages people to use __version__).
 
> --david
> 
> PS: Marc-Andre, how do you get these nice bullet characters in your
>     emails? What character is that? =)

It's chr(183) in Latin-1: the famous center dot ;-) I've tweaked
my keyboard setup to have it handy...

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