[Top][All Lists]

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

Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented c

From: Dmitry Gutov
Subject: Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision
Date: Sun, 17 Apr 2016 03:17:54 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0

On 04/15/2016 04:23 PM, Michael Albinus wrote:

I disagree. The manual is the documentation for the users, to explain
in depth, give examples, et cetera. The docstrings and VC's internal
documentation have to stand on their own. It would be silly if the
difference between `vc-backend' and `vc-responsible-backend' were to
only be explained in the manual, but not in the docstrings.

Are we speaking about different manuals? I'm speaking about the ‘GNU
Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual
dedicated to users).

OK, so the Emacs Lisp Reference is a counter-example. And it contains a narrative that explains different aspects of Emacs Lisp in a sort-of seamless fashion, which is great, because there's no good way to do that with just docstrings.

And then it goes ahead and provides its own versions of descriptions for functions and variables that are different from the docstrings, and are often longer, but sometimes shorter (e.g. for `obarray'), and at times it seems like the only reasons for the existence of the two versions is to have docstrings in the imperative voice, and the pieces of text in the manual, in the passive voice.

And then the two versions start to diverge. For instance, the docstring for `mapatoms' is rather short. The manual entry for it is longer, *and* it documents that `mapatoms' returns nil. Why would someone put that piece of information into the manual, but not the docstring, is beyond me.

So, to be clear, I dislike the ambiguity that manuals that try to be all-encompassing, like this one, create about the main source of information about each function.

reply via email to

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