[Doc-SIG] docstring grammar

[Fred L. Drake, Jr.]

Guido van Rossum writes:
 > One issue: if I'm sloppy in my writing, I could easily have escape
 > sequences like \n in the doc string that are expanded by the
 > importing.  E.g. the comments for asynchat contain sentences like
...
 > Just an annoyance, but something that the tool needs to consider.

  I don't think the concern is likely to go away by using a
parse-based approach.  Get your docstrings write or you've got a real
newline!
  Anyway it gets done, I don't think there's any call for tons of
magic interpretation for the escapes you put in your docstring.  We
don't want to introduce the magic-python-docstring-extraction
encoding.  The only reasonable way I know to get the actual string
from the parse tree is to yank the string representation of the
token.STRING node and eval() it.  Otherwise I have to re-write the
escaped-string to Python-string conversion in Python for both raw and
cooked strings.  If I have to consider screwed up strings on top of
that, we're back to the HTML-as-practiced problem.  I've done that
once, and don't plan to do it again!

 > (Now going back to trust-Fred-and-David mode :-)

  That's right.  Go back to sleep, go back to sleeep.....


  -Fred

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