[Doc-SIG] docstring grammar

M.-A. Lemburg mal@lemburg.com
Fri, 03 Dec 1999 11:25:03 +0100

"Fred L. Drake, Jr." wrote:
> M.-A. Lemburg writes:
>  > This raises the question of whether to parse or evaluate the
>  > loaded module. Evaluation has the benefit of providing "automatic"
>   Guido agrees with me on this one, sorry: it must be extractable from
> the parse tree.  Evaluation of module code is a *huge* no-no; we
> should be able to run documentation tools on unknown (== untrusted)
> code.

That's why gendoc has a switch to be able to either parse
the module or import it. Note that imports are the only way
to extract information from C extensions.

>  > 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.
>   No, these will always be hard in Python.  Order of imports can be
> significant, and the set of imports can change over the life of a
> module (imports can be delayed to reduce startup time, or a number of
> alternatives may be supported).

I guess that's the price you have to pay for *automatic*
documentation extraction. 

Perhaps there is a way to only extract class/function/method
__doc__ strings from pyc-modules without actually running them,
since those are really our only targets.

[looks at some module code objects...]

It wasn't obvious from the code objects I just looked at,
but there could be way... after all the information must hidden
somewhere between those bytes codes ;-)
Marc-Andre Lemburg
Y2000:                                                    28 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/