[Top][All Lists]

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

Re: Docstrings and manuals

From: Phillip Lord
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 13:55:16 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux)

Eli Zaretskii <address@hidden> 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.


reply via email to

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