RE: Docstrings and manuals

[Drew Adams <drew.adams@oracle.com>]

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

+10 to what Eli and Michael are saying.

Neither doc string nor manual serves the purpose of
the other.  The manual is not Javadoc.

It is up to humans to write the most appropriate text
for each, and to make coherent any differences in
message or presentation.

Differences should be based on the context (including
readers) and should not involve contradiction in
meaning (semantics, behavior) of the things described.

IOW, both need to be faithful descriptions of those
things.  There can be differences in degree of
abstraction or of precision.  But within a given level
of abstraction/precision, each must be a faithful
picture of the behavior it describes.

The same is true of any other communication about these
things to users, including tooltips and error messages:
The behavior/meaning of the program being described is
the same, and that needs to be reflected in a lack of
contradiction wrt description of that behavior/meaning.