Re: Docstrings and manuals

[Michael Albinus]

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.