Re: Docstrings and manuals

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 13:50:35 +0300
> Cc: Glenn Morris <address@hidden>, emacs-devel <address@hidden>
> 
> On 04/17/2016 11:49 AM, Michael Albinus wrote:
> 
> > We will always find examples where the entries in the manual are
> > inferior, compared with the docstring. We will also find examples with
> > incompatible information in the docstring and the manual.
> 
> The `mapatoms' manual entry is neither. And yet, wouldn't you agree that 
> it's problematic?

If you mean that mapatoms' doc string is too terse and omits some
details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
please elaborate.

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

No, it's not secondary.  It should be an expanded and augmented
version of the same information.

> Right now, I have no idea which one is supposed to be the primary source 
> of truth.

Both.  There's more than one way to tell the truth.