[Top][All Lists]

[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 22:59:21 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

On 04/17/2016 06:12 PM, Eli Zaretskii wrote:

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.

I'd rather minimize rephrasing in the manuals, while still allowing the "glue" text. Instead of having two ways to describe each important variable, I'd rather have just the docstrings, which could be adjusted to be more approachable. That would require some new Texinfo syntax to "insert the docstring here".

The narrative can still be free-form, but at least there would be one fewer source of duplication.

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.

The counterpart to "glue" text outside of the manuals is the Commentary section usually. While they're also terse usually (but not always), they aren't bound by the limitation that a docstring has to relate to a particular symbol.

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.

That sounds fine, and maybe this way is best for the more complex subjects, but in general I'd prefer to see docstrings also written with readability in mind. Then, when writing a manual section, you'll only need to write the "glue" text, and pick which symbol references, with docstrings, to add, and in which order.

reply via email to

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