Re: docstrings and elisp reference

[Eli Zaretskii]

> From: Jean-Christophe Helary <address@hidden>
> Date: Tue, 6 Jun 2017 14:10:19 +0900
> 
> Having a mechanism that generates automatic documentation (a la javadoc) 
> would be extremely valuable.

It could be valuable, but IMO only if we exercise a lot of discipline
in producing those comments.  Because every project which uses this
methodology that I looked at ends up providing _abysmally_ inadequate
documentation.  As one very typical example, look at the GTK docs,
e.g.  here:

  https://developer.gnome.org/gtk4/stable/GtkWindow.html