Re: Docstrings and manuals

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 14:42:28 +0300
> Cc: Glenn Morris <address@hidden>, emacs-devel <address@hidden>
> 
> On 04/17/2016 02:16 PM, Michael Albinus wrote:
> 
> > No primary or secondary. If docstring and manual are inconsistent, it is
> > a bug which must be fixed.
> 
> What's "inconsistent" in this case? They are almost always different.

They can be different, but still consistent.  There's more than one
way to tell the same story, without contradicting the others.

> > There is no automatism that the docstring is
> > always right, and the manual is wrong in this case. It could be also
> > vice versa.
> 
> Wouldn't it be better if we had this "automatism"?

No, not IMO.

> I'm not arguing in favor of leaving mistakes in the manual. But I think 
> it should be strictly a derivative work. I.e. the docstrings must 
> contain the complete information (if maybe presented in a terse 
> fashion), and the manual could rephrase that, only to make it more 
> accessible (but not more informative).

Once you allow rephrasing, you already allow deviation.  And there
really is no way around allowing it, because a manual that includes
only the doc strings with a minimum "glue" is much less palatable.
You can look at Guile as one example; GnuTLS is another.  Such manuals
are much less useful, IME, than what we have in Emacs.

One thing that you will never find in doc strings is a discussion of
merits and demerits of different ways of solving some problem,
especially if such a discussion requires to jump back and forth
between these ways, in order to make some point.

IOW, writing a good manual is still a human activity that cannot be
easily automated.  Ideally, doc strings should be phrased like
reference material, covering all the traits as tersely as possible,
while the manual should provide an easier reading with more continuity
text and even some explanations why things are the way they are.  At
least IMO.