[Doc-SIG] docstring grammar

[M.-A. Lemburg]

"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/