Re: docstrings and elisp reference

[Jean-Christophe Helary <jean.christophe.helary@gmail.com>]

> 2017/06/06 9:09、Tino Calancha <tino.calancha@gmail.com>のメール:
> 
>> I was thinking (naively?) that having the docstrings on one side and the reference on the other side was not a very efficient way to maintain documentation. Is everything in the documentation actually written by hand based on the docstrings? Wouldn't it be nicer to have good docstrings and use them directly in the documentation to avoid duplication of work? Is there any reason I'm not seeing why this is not happening?

> Hi,
> 
> you might wish to read the following thread:
> https://lists.gnu.org/archive/html/emacs-devel/2016-04/msg00452.html

Wow, did I open a can of worms... :)

Fascinating thread.

Just a few comments.

Having a mechanism that generates automatic documentation (a la javadoc) would be extremely valuable. By just having that "reference" it would suggest developers to adopt a more standardized format/style.

The elisp reference should definitely extend the descriptions by adding exemples so that people learn from reading (which is admittedly difficult with the docstrings only). Maybe not go as far as a cookbook, but a bit more than what we have would be very welcome (there is a *huge* gap between the Introduction and the Reference).

My initial worry is that the day we start l10n (and we'll get there eventually :), we're going to have a huge amount of redundancy. But the flip side is that we're going to have also a huge amount of feedback on both the docstrings and the elisp reference...

Jean-Christophe