[Doc-SIG] Re: docstring signatures

[Greg Ward]

On 24 March 2001, Edward D. Loper said:
> Hm.  I guess I should have thought to ask the BDFL about all this 
> before now. :)  Makes me wonder if he'll like/accpet *any* of the
> stuff we've been talking about.  But it's interesting to hear 
> that Guido is ok with a real markup language.
> 
> So are there any vocal opponents of using a real markup language
> on doc-sig right now?  (Assuming that Guido doesn't want us
> to use something like ST)..

I've been lurking throughout this whole thread (and occasionally leaning on
the "D" key... sorry guys... ;-), mainly because it sounds like you're on
the right track but you're doing the boring plodwork.  Thank you, keep it
up, etc. etc.

However, I would just like to state for the record that I am not -0, or -1,
but more like -1e6 on putting a "real" markup language in docstrings,
assuming that the set of "real" markup languages is limited to {Tex-like
languages, SGML-like languages}.  I consider both to be misbegotten freaks
that completely ignore the human factors of writeability and readability.

> Of course, on the other hand, if we can clean ST up enough, and
> make it formal, maybe he'll be ok with it.
> 
> I'm going to put my PEP on hold for now, until we figure this stuff
> out.. (if anyone wants to see what I've written so far, though,
> I'll be happy to send you a copy -- just email me).  
> 
> I'm also thinking of putting together a "minimal" ST-like language,
> that would include markup for:
>     * lists
>     * emph
>     * literals (one type, probably using '#' as delimiters)
>     * urls (using '<>' delimiters)
>     * literal blocks

Larry Wall has been there and done that: "man perlpod" if you're on a
properly administered Unix system.  ;-)  POD is really easy to write, and
pretty easy to read (human) and parse (software).  The high-level POD syntax
(where /\n\n=[A-Z]+ .*\n\n/ denotes a section delimiter) is closely tied to
Perl and irrelevant to Python, since Python already has a way of saying
"this text is documentation for module/class/function 'foo'".  But the
within-paragraph markup convention -- "this is a C<code_snippet>, this is
B<bold>" is pretty easy and useful.  Like ST, it could stand a bit of
formalization, although that has improved greatly in recent years with Brad
Appleton's Pod::Parser family of modules.

Althought I've never used ST, my understanding is that ST and POD are pretty
semantically similar, and with very similar goals: easy-to-write,
easy-to-read, minimal markup that's "good enough" for generating man pages
HTML documents, and plain text.  They both suffer from lack of
formalization, although I think POD is better nowadays.

> But maybe we'd be better off just using XML.. :)  or something like
> javadoc ('@param(x) foo..', etc.)..

If I ever see XML in a Python docstring, I think I'll go running back to
Perl.  ;-)  XML is many things to many people, but it most certainly is not
fit for human consumption.

OTOH, I quite like Javadoc's "@param", "@return" syntax.  It's easy to
write, easy to read, easy to parse, and just formal enough so that doc tools
can make sense of it.  It might be more Pythonic to spell those "param:",
"returns:", though.  ;-)

        Greg