[Doc-SIG] docstring grammar

[David Ascher]

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
=3D).  I'm afraid that parsing is all we can do safely with the Python code=
=2E
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.

> Some notes on the proposal:
>=20
> =B7 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.

> =B7 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!

> =B7 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.

--david

PS: Marc-Andre, how do you get these nice bullet characters in your
    emails? What character is that? =3D)