[Top][All Lists]

[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...


reply via email to

[Prev in Thread] Current Thread [Next in Thread]