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