[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Emacs-diffs] master 2475687: Improve documentation changes of a rec
Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit
Sun, 14 Apr 2019 23:34:25 +0300
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1
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.
In this case, the
original doc string of json-parse-buffer said almost nothing useful,
It gave the gist, described the behavior unique to the current function,
and directed the reader for more details about the behavior.
Which was quite enough for me to learn how to use it, and where the
improvement should be.
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.
I would maybe add "returns a Lisp structure corresponding to the JSON
text contained in the buffer" to the original docstring. Enumerating the
possible return values means creating more places where the doc can
become out of date. And we don't have a linter for those mistakes.
And enumeration of the optional keyword arguments sounds one more step
removed from "the main part of the doc" to me.
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.
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
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".
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.
Whereas in the case of the manual they might have to go back a page, for
Anyway, this is my opinion. Sorry if you heard all of this before already.