Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 06:03 PM, Eli Zaretskii wrote:

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

That someone saw fit to put "Then it returns ‘nil’" into the manual when 
it's not in the docstring. And that it's easy to make such a mistake.

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

Either you're saying the same as me (when writing a manual, you 
elaborate, but not add new essential new information, and thus make a 
derivative), or I don't understand how to produce the manual entries.

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

Both of them are necessarily fallible, it seems.