RE: docstrings and elisp reference

[Drew Adams <drew.adams@oracle.com>]

> What's important to understand here is that docstring documentation
> is of very limited use. This applies to both Emacs docstrings and
> everything created by javadoc and its cousins.
> 
> Let's say I want to do something with an API that I have no prior
> knowledge of and I have only the docstring documentation. I start by
> searching docstrings for something that looks vaguely useful for solving
> the problem at hand. Would the first thing(be it a class, or a function)
> I found be the optimal solution?
>
> Maybe there's actually a more
> specialized version of this function that better suits my case. Or maybe
> it's the opposite - I stumbled into a specialized function, where the
> broader one is more suited for me. There's no way to know until you read
> everything that looks even slightly important.
> 
> Because of this, the documentation needs some glue, that puts separate
> elements into a proper context. Docstrings are incapable of solving this
> problem yet. You can't just have docstrings that go "if you find this
> function useful, maybe you actually need this-other-function or maybe
> this-totally-other-function".
> 
> The key word here is _discoverability_. Because of this, you can't just
> dispose for example of Elisp manual, since it's exactly that rug that
> ties the room together.

+1.  Plus: the source code - in particular, Lisp.
That's the glue behind the glue and the single source of
information and truth.  (Well, not quite single - see C.)

A typical such quest might lead from one or more doc strings
to the Elisp manual, and then to source code - to find the
most useful functions and variables to use, or to find parts
of the code that are enlightening or useful for constructing
new code for the job.

Or it might lead from the Elisp manual to one or both of
the other sources of such info.  Or it might lead from
a single doc string to the source code.  Or back & forth.

All three are useful: doc strings, Elisp manual, source
code.  They overlap, but they also complement each other,
sometimes in terms of information content but mainly in
terms of presentation, audience, and means of access.
It's all in the source code, but the other, help, features
often facilitate discoverability and improve understanding.

Similarly, other help commands and functions: apropos etc.

Yes, Java source code is also consultable.  But I think
that the boost that you get from combining the various
information sources that Emacs offers is something more.

I don't think that JavaDoc (especially typical JavaDoc!)
plus source code gives you what you get with Emacs.

Partly that is due to Lisp being what Lisp is, perhaps,
but it is also probably due to the ubiquitous and
fine-scale attachment of doc/help to code and even to
Lisp symbols.

The comment above about "typical JavaDoc" is really
meant to emphasize this other aspect of Emacs help:

It is good not just because the constructs of doc
strings and manual _exist_ but because key people
in Emacs development have long insisted on their
importance.  Just being able to attach doc strings
or create JavaDoc is not enough.  You also need a
commitment to using them to create good help.

Good help does not fall from the sky.  It does not
come for free, generated from the source code.

Why?  Because part of the job of coming up with
good help involves addressing the possible
audiences, contexts and use cases.  Unless and
until info about that is encoded in the source
code, it needs to be added.  (And encoding it in
the source code would involve the same "user
documentation" work.) 

IMHO, that commitment is the most important factor -
the glue behind the glue.  Let's hope it continues.

There is no substitute for careful human time and
clear eyes devoted to help/doc.  No degree of
"reuse" or generation of deliverables can substitute
for that.  Tools are fine, but they don't replace
paying attention.