[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings and elisp reference
From: |
Jean-Christophe Helary |
Subject: |
Re: docstrings and elisp reference |
Date: |
Tue, 6 Jun 2017 14:10:19 +0900 |
> 2017/06/06 9:09、Tino Calancha <address@hidden>のメール:
>
>> 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
- docstrings and elisp reference, Jean-Christophe Helary, 2017/06/05
- Re: docstrings and elisp reference, Tino Calancha, 2017/06/05
- Re: docstrings and elisp reference,
Jean-Christophe Helary <=
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/06
- Re: docstrings and elisp reference, Stephen Leake, 2017/06/06
- RE: docstrings and elisp reference, Drew Adams, 2017/06/06
- Re: docstrings and elisp reference, Etienne Prud’homme, 2017/06/07
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/07
- Re: docstrings and elisp reference, Chad Brown, 2017/06/08
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/08
- Re: docstrings and elisp reference, Eli Zaretskii, 2017/06/08
- Re: docstrings and elisp reference, Jean-Christophe Helary, 2017/06/08
- Re: docstrings and elisp reference, Chad Brown, 2017/06/08