From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit Date: Sun, 14 Apr 2019 17:40:28 +0300 Message-ID: <835zrgk5ur.fsf@gnu.org> References: <20190413070933.31645.83730@vcs0.savannah.gnu.org> <20190413070934.DDF7B202C6@vcs0.savannah.gnu.org> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="114054"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 14 16:40:48 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hFgJM-000TZ8-1o for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 16:40:48 +0200 Original-Received: from localhost ([127.0.0.1]:36441 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFgJK-0000J2-Oz for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 10:40:46 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:47880) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFgJF-0000Cy-6W for emacs-devel@gnu.org; Sun, 14 Apr 2019 10:40:42 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:40098) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFgJE-00053r-Gt; Sun, 14 Apr 2019 10:40:40 -0400 Original-Received: from [176.228.60.248] (port=2209 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hFgJE-00056U-1i; Sun, 14 Apr 2019 10:40:40 -0400 In-reply-to: (message from Dmitry Gutov on Sun, 14 Apr 2019 13:34:51 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:235439 Archived-At: > From: Dmitry Gutov > Date: Sun, 14 Apr 2019 13:34:51 +0300 > > FTR, I quite dislike this kind of duplication in docstrings. 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. In this case, the original doc string of json-parse-buffer said almost nothing useful, 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. Especially for a function whose name doesn't necessarily speak volumes about its purpose. > 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". 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. > Here you seem to have made the reverse choice. I didn't like the original doc string, yes. The manual I didn't change, it was written that way to begin with.