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

[Dmitry Gutov]

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.