Re: Docstrings and manuals

[phillip.lord@russet.org.uk (Phillip Lord)]

Eli Zaretskii <eliz@gnu.org> writes:
>> 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.


I think that the two should have a different purpose. I would like more
"tutorial" information in the manual (in the sense of "here is a bit of
code that does something with the functions we are discussing at this
point"), while the docstrings should be the main documentation.

For myself, I think, being able to get to the docstring easily (probably
with a tooltip) from any occurrence of a function or variable in the
manual would be excellent.

Phil