Re: Docstrings and manuals

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 16:12:05 +0300
> Cc: Glenn Morris <address@hidden>, emacs-devel <address@hidden>
> 
> 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.

yes, we should update both the doc strings and the manual(s).

> 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.

The doc strings and the manual should convey the same information,
where they both cover the same turf.