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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 14 Apr 2019 23:34:25 +0300
> 
> On 14.04.2019 17:40, Eli Zaretskii wrote:
> 
> > 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.
> 
> I hope you are taking in consideration the increased overhead of 
> maintaining it when adding further changes to either of these functions.

I did.  We have enough similar doc strings already; one more or less
won't change anything.

> > Especially for a function
> > whose name doesn't necessarily speak volumes about its purpose.
> 
> Which of the two functions? Both of them seem to have pretty apt names.

Not IMO.  "Parse" is ambiguous, and doesn't hint on the fact that
these functions produce a Lisp representation of a JSON object.

> > Doesn't sound like something I'd say, not to that effect.  "Allowed",
> > yes; but not "required".
> 
> Even if it said "Allowed", I'd interpret it like "I'm allowed to 
> structure the documentation this way, without expecting somebody else to 
> come later and rewrite it with increased duplication".

Please don't take my changes as some kind of indirect accusation
against you.  It was just a routine maintenance job, something I do
almost every day when I see documentation that can be improved.

> > 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.
> 
> When one references another? It's always fast for the user to navigate 
> to the other docstring.

It's at least one more keystroke.  More importantly, the doc strings
are slightly different, because some of the things one function does
make no sense for the other.  So the reader will also have to decide
which parts are not relevant.