From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] master 2475687: Improve documentation changes of a recent commit Date: Sun, 14 Apr 2019 23:34:25 +0300 Message-ID: <09715d71-19d0-fe94-f819-581e89078d84@yandex.ru> References: <20190413070933.31645.83730@vcs0.savannah.gnu.org> <20190413070934.DDF7B202C6@vcs0.savannah.gnu.org> <835zrgk5ur.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="94667"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 14 22:35:17 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 1hFlqN-000OPv-Ax for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 22:35:15 +0200 Original-Received: from localhost ([127.0.0.1]:40670 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFlqL-00005x-TF for ged-emacs-devel@m.gmane.org; Sun, 14 Apr 2019 16:35:13 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:44493) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hFlpg-00005s-Pa for emacs-devel@gnu.org; Sun, 14 Apr 2019 16:34:33 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hFlpf-00070E-OU for emacs-devel@gnu.org; Sun, 14 Apr 2019 16:34:32 -0400 Original-Received: from mail-lj1-x22f.google.com ([2a00:1450:4864:20::22f]:40840) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hFlpf-0006yx-CA; Sun, 14 Apr 2019 16:34:31 -0400 Original-Received: by mail-lj1-x22f.google.com with SMTP id q66so13663727ljq.7; Sun, 14 Apr 2019 13:34:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=rIZmiSxYw2T1d+6hi+RDyK0awrTyCD+0vCMbaE9C+CE=; b=u35Tyy/EwamuJrYr1WdjTXItBMUnH7SE0fS5DfRDaWUKt3QacnSn0v7cHIuXp76BgA 8COubzs9oyJUP50Pq0Sf/aoK4yHGaG2RTx3SeptcbO7QzWJeZcU1jyA8lxC5+ulPOOCf o1BfLLm8JWZ8ZQnDWnZQDJd5dtSt+BZykH/TQwaNAYyWf6KYDQQIKcUpmRkXCgGbeILt n0TS7UrFZUTvAqutWF9GORjdJClcMiOFpIeGIybKMWaKPhYTptcBzAvUveh0UMldRL35 KTA7ai+wV4+jhAhHGTTvKvCmGu3duV3+bnn2tpy9FErkb1ebS0GPhjvvKJ1X1OvhXG23 MbSQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=rIZmiSxYw2T1d+6hi+RDyK0awrTyCD+0vCMbaE9C+CE=; b=azwYbxpB+d4jQiedKtCBR9+WToPMntVJy01OUjNBkiDuVDO+Koaue4sR1u8dmWS/S7 XYI+fLqDco0C57uxdmxoIimLa6VxGqj1xm9fYFqy//mAhF8BvXtEE55aJDmSOBClcrZY NpVyAMtmwSEgg6ERfrQZcmevsnLiXz1DSm3G/O8s0JbhbZufWhPGWAbMslA49XgIAgOp PcNZIOF5q37KvCGtVAPXcPfC7Qy7OaT95NQCWvWGrwpSIrGjanSYQI+Kpm3fkM0QZ75x n7Zxx1VTYlVPO36A94U4tjXxlfl987JKQyUlUlZNVte0rloXpLbYLyFftb3c2R1La7wu clkQ== X-Gm-Message-State: APjAAAVF+0BeDi3cXfyh/nx2lWHtlLTHA1FW5U9LwrkjvFYW0I2e13Sx zvU8NaNHBrEw/JbQAZ7u3C5oOVSa X-Google-Smtp-Source: APXvYqxZmZQ9Q2T6WSQVfa/O75fKKGF5yYsIN5Mjy8qymxClI6trZ1rBLEDJe/miCn/tjnMN/+6QgQ== X-Received: by 2002:a2e:9753:: with SMTP id f19mr36905082ljj.54.1555274069093; Sun, 14 Apr 2019 13:34:29 -0700 (PDT) Original-Received: from [192.168.1.3] ([185.105.174.23]) by smtp.googlemail.com with ESMTPSA id w3sm9687572lji.59.2019.04.14.13.34.27 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 14 Apr 2019 13:34:28 -0700 (PDT) In-Reply-To: <835zrgk5ur.fsf@gnu.org> Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::22f 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:235458 Archived-At: 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.