[Python-Dev] Online help scope

[Tim Peters]

[Paul Prescod]
> I think Guido and I are pretty far apart on the scope and requirements
> of this online help thing so I'd like some clarification and opinions
> from the peanut gallery.
>
> Consider these scenarios
>
> a) Signature
> ...
> b) Usage hint
> ...
> c) Complete documentation, paged(man-style)
> ...
> d) Complete documentation in a user-chosen hypertext window
> ...

Guido's style guide has a lot to say about docstrings, suggesting that they
were intended to support two scenarios:  #a+#b together (the first line of a
multi-line docstring), and #c+#d together (the entire docstring).  In this
respect I think Guido was (consciously or not) aping elisp's conventions, up
to but not including the elisp convention for naming the arguments in the
first line of a docstring.  The elisp conventions were very successful
(simple, and useful in practice), so aping them is a good thing.

We've had stalemate ever since:  there isn't a single style of writing
docstrings in practice because no single docstring processor has been
blessed, while no docstring processor can gain momentum before being
blessed.  Every attempt to date has erred by trying to do too much, thus
attracting so much complaint that it can't ever become blessed.  The current
argument over PEP 233 appears more of the same.

The way to break the stalemate is to err on the side of simplicity:  just
cater to the two obvious (first-line vs whole-string) cases, and for
existing docstrings only.  HTML vs plain text is fluff.  Paging vs
non-paging is fluff.  Dumping to stdout vs displaying in a browser is fluff.
Jumping through hoops for functions and modules whose authors didn't bother
to write docstrings is fluff.  Etc.  People fight over fluff until it fills
the air and everyone chokes to death on it <0.9 wink>.

Something dirt simple can get blessed, and once *anything* is blessed, a
million docstrings will bloom.

[Guido]
> That'S What Some People Think.  I Disagree That It Would Be Either
> Feasible Or A Good Idea To Put All Documentation For A Typical Module
> In Its Doc Strings.

I'm with Paul on this one:  that's what module.__doc__ is for, IMO (Javadoc
is great, Eiffel's embedded doc tools are great, Perl POD is great, even
REBOL's interactive help is great).  All Java, Eiffel, Perl and REBOL have
in common that Python lacks is *a* blessed system, no matter how crude.

[back to Paul]
> ...
> No matter what we decide on the issue above, reusing the standard
> documentation is the only practical way of populating the help system
> in the short-term. Right now, today, there is a ton of documentation
> that exists only in LaTeX and HTML. Tons of modules have no docstrings.

Then write tools to automatically create docstrings from the LaTeX and HTML,
but *check in* the results (i.e., add the docstrings so created to the
codebase), and keep the help system simple.

> Keywords have no docstrings.

Neither do integers, but they're obvious too <wink>.