Re: Docstrings and manuals

[Eli Zaretskii]

> Cc: address@hidden, address@hidden, address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 18:15:17 +0300
> 
> 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.

Making mistakes is always easier than avoiding them.  I don't think
this fact is significant.

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

To produce a good manual text, you need to try to describe and explain
the subject in some logical way.  The result is not a derivative, in
that it doesn't necessarily repeat the doc strings and then adds some
more stuff (although doing that is sometimes TRT).  It could be that
most of the text of the manual section has no direct relation at all
to the doc strings.  It could even be an entirely different POV of
looking at the subject.  E.g., compare the node "Generic Functions" in
the ELisp manual with the doc strings of the symbols covered by that
node.  As an even more extreme example, compare the node
"Bidirectional Editing" in the user manual with the doc strings of the
3 variables it covers.

> > Both.  There's more than one way to tell the truth.
> 
> Both of them are necessarily fallible, it seems.

Of course.  "To err is human".