[Top][All Lists]

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

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

From: Dmitry Gutov
Subject: Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit
Date: Mon, 15 Apr 2019 18:42:50 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1

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.

reply via email to

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