Re: docstrings and elisp reference

[Etienne Prud’homme]

Richard Stallman <address@hidden> writes:

> I could be mistaken, but I think that Javadoc is comparable to Emacs
> Lisp doc strings.

Emacs Lisp doc strings have support for some of JavaDoc features, but
cannot compare in many things.  Many things described in doc strings are
informal and are pretty difficult to extract.  For example, we have no
formal way of telling:

- the type of the function return value
- what exceptions can be thrown from the function
- does this function has side effects
- since when it was introduced
- it’s a hook variable
- if the comment includes a file system path in the example

And many other things I don’t have in mind now.

Of course, some of those things are directly addressed with options
variables.

> If that is correct, then of course Javadoc documentation is useful.
> Emacs Lisp doc strings are useful too.  But concatenating them does
> not make a clear tutorial/reference manual.  We need both!
>
>   > However, I also think Jean-Christophe makes a good point about
>   > documentation generation.  Not with duplication, but semantic support.

> What is "semantic support"?

It is more or less tagging useful information about the content
generated.  Particularly useful when doing indexation of either comments
or the documentation.  As I said another response, _I have mistaken_
some other GNU tools that I tried to port at the same time as the Emacs
Lisp manual.

I think it could apply to both the reference manual and the doc strings
in general.
                                                                      
>   > GNU projects are almost nonexistent.
>
> You can't mean that literally, so what do you mean?

The tool I described is an offline documentation viewer.  The docset is
what is interesting.  What we usually call docset is a tarball with the
documentation and an index tagging the documentation.  The index is a
standardized SQLite table with a restricted set of identifiers and their
classes.  There are several programs allowing searching this
documentation standard.  Zeal is an example, but the _helm-dash_ MELPA
package also offers a basic interface for searching the docs.

In order to make a docset, we can use documentation generators like
JavaDoc, Doxygen, etc.  We can also use the online documentation
provided by the project.  This way, the documentation is either fetched
from the website (like Mozilla Developer Network) or the HTML version of
a project is taken.

To make indexation, we generally make small programs to record all
functions/macros/variables/... and their reference in an HTML document.
This way, the index can easily be updated when the documentation changes
without having to review each references.

Therefore, for an index to be created, we either have to use Natural
Language Processing (which we never do) or use some kind of clues in the
HTML document describing the type of information to index.

The perfect way would be to use XML directly, but few or no projects use
it.  We instead rely on the HTML tag class names from the documentation
documents.  Almost every time, they can be really helpful to know the
type of the tagged information.  Most developpers making the CSS
stylesheets use names like “function” (or an other arbitrary name) when
tagging the functions.  That’s the same for variables, macros, etc.

That is where _most_ GNU projects seem to lack the capability.  It looks
like Jean-Christophe was right in pointing out it might be because we’re
not using HTML exporting templates at its best.

GNU projects are usually harder to index because of that.  Thus we have
a minority of GNU tools listed.  I’m not saying that for criticizing
GNU, but I think it’s an important issue we could address in the near
future.

Of course, this discussion is about Emacs.  I hope I clarified some of
what I said.

--
Etienne