[Doc-SIG] Re: docstring signatures

[Edward D. Loper]

> >         * Intuitiveness: [...]
> >         * Ease of use: [...]
> 
> Of course.  This is all apple pie and motherhood.  nobody will want
> documentation that's unintuitive or hard to use!

Not necessarily -- Many people use Javadoc, and it's not "easy to
use"; and I would argue that LaTeX is not "intuitive," as I defined
it..  These design goals have specific consequences, like ruling
out "heavy-weight" formalisms...

> >         * Expressive Power: The formatting conventions must have
> >           enough expressive power to allow users to write the API
> >           documentation for any python object.
> 
> I've never found that plaintext got in the way of my expressiveness.

It depends on whether you want to express things to people or to
computer tools.  People are very good at reading plaintext docstrings,
and getting the appropriate info out of them.  But that doesn't mean
it's easy to write a tool to do the same..  I believe that formatting
conventions should have enough expressive power, for example, to
distinguish between regions that can be rendered in non-monospaced
font, & word wrapped, and those that should be rendered as "literal."

> >         * Simplicity: [...]
> More motherhood.

Again, I disagree.  Neither HTML nor LaTeX is *simple*.  

> >         * Safety: No well-formed formatted documentation string should 
> >           result in unexpected formatting.  This goal derives from
> >           intuitiveness.
> This is a good one.  ST loses big here!

Well, at least STclassic and STNG.  That's the reason why I would 
vehemently oppose using them.

> I though Javadoc was geared too much towards generating HTML; we
> should not focus too much on HTML.

It was initially geared towards generating HTML, although they have
tools to render it in LaTeX, emacs info files, framemaker, etc.
Most of these tools work by requiring that you not use arbitrary
HTML tags in your docs, but just limit yourself to a limited set
(<CODE/>, <UL/>, <DL/>, <OL/>, etc.. usually 15-50 tags, depending
on the tool).  

Also, there are 2 orthogonal features of Javadoc:
  1. their ability to use HTML in comments (which I don't think we
     should adopt)
  2. their ability to mark special values, using forms like:

      @param(x) description of x...
      @throw(y) description of when y is thrown..

I think we should have something like (2), although it might be more
pythonic to do something like:

    argument x: description of x
    throw y: description of y

or:

    arguments:
        x -- description of x
        y -- description of y

(incidentally, this use is the main reason that I support DLs in
documentation strings..)

-Edward