Re: Docstrings and manuals

[Dmitry Gutov <dgutov@yandex.ru>]

On 04/17/2016 07:23 PM, Eli Zaretskii wrote:

> 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 should be a derivative in the sense that it's produced based on 
knowing the docstrings and the common context they're used it. But not 
some additional inner details about each symbol that never made it into 
docstrings, I think.

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

Bidirectional Editing is fine. It describes a facility that's largely 
implemented in C, so the three variables are just a small part of it.

Generic Functions, on the other hand, may be indicative of the problem 
that I've brought up: the descriptions of `cl-defgeneric' and 
`cl-defmethod' and much longer in the manual than their docstrings 
(especially the latter one). I see no particular reason for them to be 
different in this case.

Maybe that will require restructuring the manual text to move the 
enumeration of the possible types (defined in cl--generic-typeof-types) 
to a separate paragraph or section, but that seems only beneficial.

Why would we want to mention that :before methods get called "in the 
most-specific-first order" only in the manual, but not in the docstring? 
And so on.

When a docstring gets too complicated, we can go the way of `cl-loop' 
to, again, avoid repeating ourselves. In that case I at least know to 
consult the manual, and which node to visit.