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: Mon, 15 Apr 2019 17:57:01 +0300 Message-ID: <83ftqjiaf6.fsf@gnu.org> References: <20190413070933.31645.83730@vcs0.savannah.gnu.org> <20190413070934.DDF7B202C6@vcs0.savannah.gnu.org> <835zrgk5ur.fsf@gnu.org> <09715d71-19d0-fe94-f819-581e89078d84@yandex.ru> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="246606"; 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 Mon Apr 15 16:57:22 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 1hG32w-00122j-4m for ged-emacs-devel@m.gmane.org; Mon, 15 Apr 2019 16:57:22 +0200 Original-Received: from localhost ([127.0.0.1]:51368 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hG32v-0002kH-4o for ged-emacs-devel@m.gmane.org; Mon, 15 Apr 2019 10:57:21 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:60263) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hG32j-0002it-VT for emacs-devel@gnu.org; Mon, 15 Apr 2019 10:57:11 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:57364) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hG32j-0000i3-Qq; Mon, 15 Apr 2019 10:57:09 -0400 Original-Received: from [176.228.60.248] (port=4463 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hG32j-0004zE-AX; Mon, 15 Apr 2019 10:57:09 -0400 In-reply-to: <09715d71-19d0-fe94-f819-581e89078d84@yandex.ru> (message from Dmitry Gutov on Sun, 14 Apr 2019 23:34:25 +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:235486 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Sun, 14 Apr 2019 23:34:25 +0300 > > 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. I did. We have enough similar doc strings already; one more or less won't change anything. > > 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. Not IMO. "Parse" is ambiguous, and doesn't hint on the fact that these functions produce a Lisp representation of a JSON object. > > 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". 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. > > 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. 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.