[Top][All Lists]

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

Re: Docstrings and manuals

From: Eli Zaretskii
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 18:14:45 +0300

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

reply via email to

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