Re: docstrings and elisp reference

[Etienne Prud’homme]

Drew Adams <address@hidden> writes:

> And this is not JavaDoc.  The Elisp manual is not purely
> and simply an API reference manual.

It’s worth mentioning that JavaDoc documentation style is particularly
useful for Object-Oriented Programming and strongly typed languages.  I
think it’s even mandatory with OOP to be readable.

However, I also think Jean-Christophe makes a good point about
documentation generation.  Not with duplication, but semantic support.
While documentation support is awesome in Emacs with GNU libraries, it’s
not always so with third-party documentation tools.  I’m thinking about
Zeal (and to a very limited extent Dash that is not free).

Those tools are highly effective for semantic indexation for newcomers
since they offer a simple interface for hundred FLOSS libraries.  GNU
projects are almost nonexistent.

I’ve been trying in the past to port GNU projects documentation and I
finally gave up.  I find Texinfo to be very limited when it comes to
semantic support.  It’s really hard to extract meaningful definitions
from texi files.