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

On 04/17/2016 03:19 PM, Michael Albinus wrote:
Dmitry Gutov <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).

I still don't understand what problem you discuss. There are docstrings,
and there are manuals. Both have their reasons to exist.

My problem is that you stated the lack of a manual as the reason for your lack of understanding of VC's internals. I'm saying the problem is them being documented insufficiently in the code. And, like I mentioned, if you go ahead and write the newfound revelations in the manual, but not anywhere else, a certain slice of developers is going to miss out.

To expand on my message in http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20637#91, an example:

If we make a decision that vc-BACKEND-state can rely on FILE not having state `unregistered' (I'm not saying we should; it's just one option), that information should go into the Commentary at the top of vc.el (probably into the description of the `state' command), but...

I believe it would be good if vc-* functions are covered in a
manual. What is the problem with this?

...if it also finds its way into a manual later, I don't see any harm.

To put a different spin on my statement earlier: if neither the docstrings, nor the manual are considered the Single Source of Truth, to read a reasonably complete description of a function, I'd have to read both the docstring and the manual. And that's just wasteful.

And even the personal preferences aside, we can't make the manual to be the SSOT because most functions are not documented there.

reply via email to

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