[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: Sun, 14 Apr 2019 23:34:25 +0300
User-agent: 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
the reader?

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

Anyway, this is my opinion. Sorry if you heard all of this before already.

reply via email to

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