[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Dmitry Gutov
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 14:42:28 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

On 04/17/2016 02:16 PM, Michael Albinus wrote:

No primary or secondary. If docstring and manual are inconsistent, it is
a bug which must be fixed.

What's "inconsistent" in this case? They are almost always different.

There is no automatism that the docstring is
always right, and the manual is wrong in this case. It could be also
vice versa.

Wouldn't it be better if we had this "automatism"?

See also the Elisp Manual (info "(elisp)Caveats")

--8<---------------cut here---------------start------------->8---
   The manual should be fully correct in what it does cover, and it is
therefore open to criticism on anything it says—from specific examples
and descriptive text, to the ordering of chapters and sections.  If
something is confusing, or you find that you have to look at the sources
or experiment to learn something not covered in the manual, then perhaps
the manual should be fixed.  Please let us know.
--8<---------------cut here---------------end--------------->8---

I'm not arguing in favor of leaving mistakes in the manual. But I think it should be strictly a derivative work. I.e. the docstrings must contain the complete information (if maybe presented in a terse fashion), and the manual could rephrase that, only to make it more accessible (but not more informative).

reply via email to

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