[Doc-SIG] docstring grammar

[Fred L. Drake, Jr.]

Edward Welbourne writes:
 > We have, it occurs to me, another important namespace: unimported
 > modules.  Thus the string module doesn't import re, I assume, but may
 > wish to refer to it (e.g. to say `this function is a cheap variant of
 > the eponymous one in re') in its doc-strings.  Fortunately, we also have
...
 > Note, however, that some bypassing of this may be achieved using the
 > [blah] notation (which is good).

  Excellent point!
  I think this can be handled very nicely by stating that the [name]
syntax use (in this order):

    1. the standard Python search sequence
    2. fully-qualified names into the standard library

  The latter can be implemented in a number of different ways
depending on the desired level of efficiency and willingness to
pre-process documentation.


  -Fred

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