[Doc-SIG] docstring grammar

Guido van Rossum guido@CNRI.Reston.VA.US
Thu, 02 Dec 1999 16:05:25 -0500


[Robin Friedrich, on runtime vs. compile-time docstring extraction]
> We could argue this forever. Gendoc solved this by collecting info either
> way, based on a runtime switch. As an author running this tool obviously I
> trust the module/package to be imported and generate the docs that way. And
> of course C module doc strings will need this feature.
> Again, this is an application issue not a doc string grammar issue.

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

# The handle_read() method looks at the input stream for the current
# 'terminator' (usually '\r\n' for single-line responses, '\r\n.\r\n'
# for multi-line output), calling self.found_terminator() on its
# receipt.

If we translate this into a doc string, either the doc string has to
be a triple-quoted *raw* string, or we'll have to double all the
backslashes, lest they be indistinguishable from real newlines:

"""
The handle_read() method looks at the input stream for the current
'terminator' (usually '\\r\\n' for single-line responses, '\\r\\n.\\r\\n'
for multi-line output), calling self.found_terminator() on its
receipt.
"""

Without doubling, this would become

"""
The handle_read() method looks at the input stream for the current
'terminator' (usually '\r
' for single-line responses, '\r
.\r
'
for multi-line output), calling self.found_terminator() on its
receipt.
"""

Just an annoyance, but something that the tool needs to consider.

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

--Guido van Rossum (home page: http://www.python.org/~guido/)