[Doc-SIG] docstring grammar

Fred L. Drake, Jr. fdrake@acm.org
Thu, 2 Dec 1999 15:10:44 -0500 (EST)


Mark Hammond writes:
 > * IMO, importing the module to extract this information is fine.  For
 > the 1% of cases where it is not and the author of the module needs to

  No, it's not.  Never trust someone else's code until you've read the 
documentation, and don't trust the documentation if they wrote it.
Well, maybe *that's* going a little too far... but import is not
acceptable.  Using the parse tree also allows the order to be
well-defined, while introspection doesn't allow that at all.

 > chance of it one day existing :-)  Indeed, do it the simple way, and
 > the first person who needs the parse-only option can help code it :-)

  I maintain that the parse tree is the simple route to getting a
reliable tool, and I am working on coding one.  Neat, huh?

 > As a final note:  The tool should be written with distinct "generate"
 > and "collate" phases, simply to resolve the cross-references.  It is
 > unreasonable to expect that all cross-references will be capable of
 > being resolved in a single pass.  Note sure exactly what this means
 > from an implementation POV, but it is important.

  Easy from an implementation POV, and that's exactly my approach.
(My intention is to be able to document entire packages at a time as
well, rather than individual modules.)


  -Fred

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