emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals


From: Dmitry Gutov
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 23:22:59 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]