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

[Dmitry Gutov <dgutov@yandex.ru>]

On 15.04.2019 17:57, Eli Zaretskii wrote:

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

I admit to being a bit nervous for the remaining "dry" docstrings.

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

Erm. Well, I thought it's a given. It is something we can explain with 
just one sentence, though (see an example in my previous message).

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

It's not personal, but it's something I'd have to deal with next time 
I'm making a change there (if that happens). I also liked the previous 
version better, or at least some aspects of it.

Speaking of routine maintenance, since you're asking for documentation 
changes together with the patches now, it might be worth it to 
standardize the approach more.

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

It's not like I disagree with the whole commit altogether. That part 
could be improved. But "refer to that other docstring for the 
description of the optional keyword arguments" is something that made 
sense to me. Enumerating all the possible return types in just one place 
is another thing.