[Top][All Lists]

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

Re: Docstrings and manuals

From: Michael Albinus
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 13:16:23 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.92 (gnu/linux)

Dmitry Gutov <address@hidden> writes:

>> This does not mean that manuals are useless. It only means, that there's
>> a bug to be fixed.
> Sure. But I think that means that we should have a policy that the
> manual is secondary to the information contained in the source
> files. Right now, I have no idea which one is supposed to be the
> primary source of truth.

No primary or secondary. If docstring and manual are inconsistent, it is
a bug which must be fixed. There is no automatism that the docstring is
always right, and the manual is wrong in this case. It could be also
vice versa.

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

Best regards, Michael.

reply via email to

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