[Doc-SIG] docstring grammar

David Ascher da@ski.org
Mon, 29 Nov 1999 10:31:05 -0800 (Pacific Standard Time)


On Mon, 29 Nov 1999, Tony J Ibbs (Tibs) wrote:

> >   Characters between # signs and the end of the line are stripped by
> >   the docstring parser.
> 
> This is a Bad Thing - I have quite often needed to discuss things in doc

As I mentioned in another email, yes, you're right.

> (Also, if one were using Tim Peter's "test using the doc string as template"
> thingy, one needs to be able to put generic Python code in the doc strings,
> and that means that stopping comment characters from going through to the
> ultimate documentation may be a bad thing.)

This raises a deeper issue: introducing Python code in a docstring.  Such
text cannot be parsed like text because linebreaks, indentation etc. are
important.  Here's one idea which I like -- introduce a new keyword which
is the equivalent of HTML's <PRE> tag:

  Code:

    def foo(): ...
       return ...

In other words, Python code is just another kind of text, but the
processing rules applied to that block are different. The only restriction
is that the text in a Code: block *cannot* be outdented more than the
first line in the block.  The rendering in HTML would omit the label
"Code:" and instead change font to the monospace font or whatnot.

One related comment:  multiple instances of a given keyword can occur
within a docstring.

> [... on the issue of how to 'shorten' lists... ]
>
> No, on thinking about it, I would vote for either:
> 
> 	1) use of white space as David proposes
> 	   (pro: utter simplicity,
> 	    con: doesn't quite look as nice as I'd like)
> 	2) allow Python list syntax
> 	   (pro: emphasises this is for short lists,
> 	    con: a bit odd)
> 	3) detect bullet characters at the "start of line"
> 	   (pro: still fairly simple,
> 	    con: one has to take care about, e.g., dashes in text)
> 	   Ah - I just realised that negative numbers at the start of a line
> 	   probably kill that one...

How about another keyword?

  List:
     * foo
     * bar
     * spam

Again, such keywords would not be rendered in 'output formats' (HTML, PS,
etc.).

> There's also a semi-convention I've seen where a module's doc string is also
> used as its documentation for Unix commands, and one substitutes in
> sys.argv[0] - i.e., the command used to invoke the script - as a string into
> the "Usage:" line. It's a rather hacky trick, and perhaps not to worry about
> too much.

I'd rather leave that to the coder who does the if __name__ == '__main__'
code.  sys.argv is a runtime-built construct, and I think docstrings
should be dependent on compile-time information only.

--david