Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit

[Eli Zaretskii]

> From: Dmitry Gutov <address@hidden>
> Date: Sun, 14 Apr 2019 13:34:51 +0300
> 
> FTR, I quite dislike this kind of duplication in docstrings.

Yes, you've said that in the past, and I think we agreed to disagree
on it.  My opinion is that it's a judgment call: sometimes duplication
is for the better, and sometimes for the worse.  In this case, the
original doc string of json-parse-buffer said almost nothing useful,
leaving almost everything to look up in another function's
documentation, which IME is annoying.  Referring to another doc string
is OK for some secondary details, or perhaps for some very complicated
issues.  Not for the main part of the doc.  Especially for a function
whose name doesn't necessarily speak volumes about its purpose.

> Didn't we discuss the difference between docstrings and manuals some 
> time ago, where you expressed the opinion that docstrings are allowed 
> the kind of "see XX for more detail" references, and it's the manuals 
> where information sometimes has to be reiterated for the convenience of 
> the reader?

Doesn't sound like something I'd say, not to that effect.  "Allowed",
yes; but not "required".  If anything, it is easier to refer to a
previous function in the manual, when two or more functions are
described one after another.  By contrast, doc strings are never
"near" one another.

> Here you seem to have made the reverse choice.

I didn't like the original doc string, yes.  The manual I didn't
change, it was written that way to begin with.