From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.bugs Subject: bug#35163: 25.1; `narrow-to-region' docstring no mention of args Date: Tue, 09 Apr 2019 02:13:17 +0100 Message-ID: <87h8b89e1e.fsf@tcd.ie> References: <868swoffpi.fsf@zoho.eu> <83ftqwb788.fsf@gnu.org> <86wok8dzi8.fsf@zoho.eu> <83bm1jbqgi.fsf@gnu.org> <86mul3bodv.fsf@zoho.eu> <83r2afa4od.fsf@gnu.org> <86zhp0urlr.fsf@zoho.eu> <87a7h0cf7p.fsf@tcd.ie> <86zhp0t26p.fsf@zoho.eu> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="82846"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: <35163@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 09 03:14:24 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1hDfLD-000LQn-JM for geb-bug-gnu-emacs@m.gmane.org; Tue, 09 Apr 2019 03:14:23 +0200 Original-Received: from localhost ([127.0.0.1]:33288 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDfLC-0004Nz-Cd for geb-bug-gnu-emacs@m.gmane.org; Mon, 08 Apr 2019 21:14:22 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:37918) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hDfL3-0004Nu-Ic for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:14:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hDfKv-0006s2-VS for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:14:09 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:36853) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hDfKt-0006qd-TF for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:14:04 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hDfKr-0001ng-Mv for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2019 21:14:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Basil L. Contovounesios" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 09 Apr 2019 01:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35163 X-GNU-PR-Package: emacs Original-Received: via spool by 35163-submit@debbugs.gnu.org id=B35163.15547724096868 (code B ref 35163); Tue, 09 Apr 2019 01:14:01 +0000 Original-Received: (at 35163) by debbugs.gnu.org; 9 Apr 2019 01:13:29 +0000 Original-Received: from localhost ([127.0.0.1]:50397 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDfKK-0001mi-MG for submit@debbugs.gnu.org; Mon, 08 Apr 2019 21:13:28 -0400 Original-Received: from mail-ed1-f66.google.com ([209.85.208.66]:44825) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hDfKI-0001mR-00 for 35163@debbugs.gnu.org; Mon, 08 Apr 2019 21:13:26 -0400 Original-Received: by mail-ed1-f66.google.com with SMTP id d11so13365091edp.11 for <35163@debbugs.gnu.org>; Mon, 08 Apr 2019 18:13:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd-ie.20150623.gappssmtp.com; s=20150623; h=from:to:subject:references:date:in-reply-to:message-id:user-agent :mime-version; bh=iJjB+g0a1tWfoymc9bAPUl5CbLmher/Xit2559U/VcA=; b=XfocpA6BzEffLsbuJNH+z6r/zHOJ+b1ZiQuRqVbPVa6cIFzu2xlKfj/V9MFNvnvCGm BcpMFDRLuxTEomlpbaQVCFFEz0YN347XtzHu4R0rYxNsIJIGJXY2ZTsZeHNuBENhY4S4 KWmC68PXlfpY9IGlrokqg6U4/4xaPfx+GJykq2mRfGbfdv7NBFl16/5xMK5nHoQJLtsg HZgsaKtQc/XRge+cN7TuBBRP6leq8+tofJMq6MWDGXYN1yrPKYdOo/SxMDR548voA1oy tr6L60cH62fL6S9tYlZn4hFHyuc7Bdq7+Al3m/gRJLJpZP01xGd/xiRJchwNvbiVkfzs GnqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=iJjB+g0a1tWfoymc9bAPUl5CbLmher/Xit2559U/VcA=; b=SsGdNJFt6uoL89J6EWU4WK4A1k9pNIlJKldsMXfXPb4JpCvs6CC82G1sdSE3ksUSF/ tySVdy7DJuu7hXw2VrSxtTwWB18PSsgcba6LHTNuhGhAG71k7oILK58uFEHOrsDwJalN H6/3np8htEsIIWmRQRiNnwVZuotGEGN45fYrZS4WIOfyKfdVes6yGi9AA0mGPPOTm846 GDAVXPxCNMFDNtIszhTtUY1qVYs4c0muOTVYUH2hH3cW4D0SICcDn/xWgwh1UUEgkdBh 0PU30YlJb3FC2JroZQHJNotceOcU8XBtmg4XUOWxZAI/PYjmnAE4hYqnLjYkyT2vRyTj c2Lw== X-Gm-Message-State: APjAAAWpqkmZEdMsRa9Em8RiTPSRoAr/Tnm7wNyyCkI63CHK5ZIq7D95 mbJdr0Xa2CYZ0fwn1a9Bga0wihCQsyfvWTYw X-Google-Smtp-Source: APXvYqy5kA3e1bwhwo2VAk1tZ4yqHl5uv5YEB3l2LpyVIxmsjlW8bfh4TiIwxjNuah/fghbpf22bYg== X-Received: by 2002:aa7:c5ca:: with SMTP id h10mr8040711eds.140.1554772399834; Mon, 08 Apr 2019 18:13:19 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:f786:805d:f4ab:1006]) by smtp.gmail.com with ESMTPSA id x54sm9235250edd.35.2019.04.08.18.13.19 for <35163@debbugs.gnu.org> (version=TLS1_3 cipher=AEAD-AES256-GCM-SHA384 bits=256/256); Mon, 08 Apr 2019 18:13:19 -0700 (PDT) In-Reply-To: <86zhp0t26p.fsf@zoho.eu> (Emanuel Berg's message of "Tue, 09 Apr 2019 03:09:02 +0200") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:157385 Archived-At: Emanuel Berg writes: > Basil L. Contovounesios wrote: > >> [ Your Mail-Followup-To and Mail-Copies-To >> headers seem wrong, they should point to >> the bug address 35163@debbugs.gnu.org >> instead of bug-gnu-emacs@gnu.org. ] > > [ OK, now I reply tho this (i.e., your) message > thru gmane.emacs.bugs, and after that, I hope > to reply to Noam Postavsky's message, and > I'll do that thru mail, and we'll perhaps see > if there is a difference or both ways are > broken. My hunch is it'll work if I use mail, > but not if I use the Gmane newsgroup. ] > > [ I was right, the Gmane newsgroups is to > blame. So I re-send it here as well. > Now everyone should be happy and content. ] Indeed, your reply to Noam correctly kept the bug report CCed, whereas your previous reply to me did not. >> They're conventions and decent guidelines for >> the general case, not rules. Humans reserve >> the right to exercise their own judgement. >> In particular, the "rule" to mention >> positional arguments in the order they appear >> often makes for unreadable docstrings IME. > > OK, the rule to mention them in order makes > sense especially if you have a function with > tons of args. But most important is that they > are mentioned exactly as they are, so they can > be searched for. Often, in Elisp code, you see > this > > > (some-function some-feature some-property t) > > > Now, you can often guess what everything does, > except for the last `t'. Brining up the help > and searching for the arg's name to find it > immediately in the docstring is a good way of > finding out, fast. I think most of us agree that docstrings, especially those of public functions, should mention their accepted arguments by name, if not in the exact same order as they appear in the argument list. Eli fixed this for narrow-to-region[1] following your report. [1: a5da653319]: * src/editfns.c (Fnarrow_to_region): Doc fix. (Bug#35163) 2019-04-08 19:53:48 +0300 https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=a5da653319a3018074debfc7b4fdd90ac7ea838c >> Eli [...] keeps himself very busy >> co-maintaining Emacs, yet he still manages to >> set a stellar example of how documentation >> should be maintained. > > ... okay? I just thought that was a strange > statement. Like someone had _denied_ that (?) No-one denied that. You said: > Should I interpret this as "one shouldn't > bother the maintainers with details like this"? So my sentence was intended as an example of how un-bothered maintainers are by details like this, in that e.g. Eli pays a lot of attention to documenting things properly, and following Emacs and GNU conventions. All I meant to say is that these documentation details aren't beneath anyone. I hope I've managed to explain myself properly. Thanks, -- Basil