Re: Docstrings and manuals

[Dmitry Gutov]

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.