[Doc-SIG] docstring grammar

[Fred L. Drake, Jr.]

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=20=

the parse tree.  Evaluation of module code is a *huge* no-no; we
should be able to run documentation tools on unknown (=3D=3D untrusted)=

code.

 > 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).

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

  That's right.  There's little need for signature repitition for
Python code.  There will be times it is appropriate, but that's the
oddball case.

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

  Definately; the search sequence should mirror that of the runtime,
and the details need not be repeated.  That's what we have the
language reference for.

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

  Definately.


  -Fred

--
Fred L. Drake, Jr.=09     <fdrake@acm.org>
Corporation for National Research Initiatives