From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#11571: 24.0.97; doc string of `dired-get-subdir-min' Date: Sun, 9 Feb 2014 14:25:27 -0800 (PST) Message-ID: <7806d41c-d4e6-45f6-bbca-4abbf0a8ba9e@default> References: <144EDF3C01664A2180447B02D1A6EB09@us.oracle.com> <484EACDE2A4A4185B158B84473AB1710@us.oracle.com> <871tzdgcmg.fsf@building.gnus.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1391984781 15660 80.91.229.3 (9 Feb 2014 22:26:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 9 Feb 2014 22:26:21 +0000 (UTC) Cc: 11571@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Feb 09 23:26:27 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1WCcpT-0002tf-Um for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Feb 2014 23:26:24 +0100 Original-Received: from localhost ([::1]:52329 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCcpT-0006y1-F5 for geb-bug-gnu-emacs@m.gmane.org; Sun, 09 Feb 2014 17:26:23 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58489) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCcpH-0006xs-Q0 for bug-gnu-emacs@gnu.org; Sun, 09 Feb 2014 17:26:20 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WCcp8-0005aS-13 for bug-gnu-emacs@gnu.org; Sun, 09 Feb 2014 17:26:11 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:46893) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCcp7-0005aO-Uc for bug-gnu-emacs@gnu.org; Sun, 09 Feb 2014 17:26:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WCcp7-000550-LW for bug-gnu-emacs@gnu.org; Sun, 09 Feb 2014 17:26:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Feb 2014 22:26:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 11571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 11571-submit@debbugs.gnu.org id=B11571.139198473719492 (code B ref 11571); Sun, 09 Feb 2014 22:26:01 +0000 Original-Received: (at 11571) by debbugs.gnu.org; 9 Feb 2014 22:25:37 +0000 Original-Received: from localhost ([127.0.0.1]:60912 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCcoh-00054J-Ua for submit@debbugs.gnu.org; Sun, 09 Feb 2014 17:25:36 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:16828) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCcoe-000545-SP for 11571@debbugs.gnu.org; Sun, 09 Feb 2014 17:25:33 -0500 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s19MPUuA003952 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 9 Feb 2014 22:25:31 GMT Original-Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s19MPTwd001024 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 9 Feb 2014 22:25:30 GMT Original-Received: from abhmp0005.oracle.com (abhmp0005.oracle.com [141.146.116.11]) by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s19MPTOQ001019; Sun, 9 Feb 2014 22:25:29 GMT In-Reply-To: <871tzdgcmg.fsf@building.gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:85101 Archived-At: > > Actually, the real bug is that `dired-get-subdir-min' has no doc > > string, so the doc string of `cdr' is used in its stead. The > > whole point of defining and using a separate function for this, > > instead of just coding with `cdr', is to enable readers of the > > code - and a fortiori the doc - to think in terms of the data > > structure of directories and not just abstract cons cells. There > > should be doc at the proper level of abstraction here. >=20 > Help says: >=20 > --- > dired-get-subdir-min is an alias for `cdr' in `dired.el'. > (dired-get-subdir-min LIST) > Return the cdr of LIST. If arg is nil, return nil. > Error if arg is not nil and not a cons cell. See also `cdr-safe'. > --- >=20 > I think that's fine. No, it is not fine. That doc is 100% unrelated to "dired", "getting" something, "subdir", and "minimum". If it were fine, then it would be even finer to get rid of this function, with its supposedly descriptive name, and use just cdr. If that is the fix you make, fine with me. If you keep the function then users deserve its doc to explain what it is about. Clearly, it is not just "about" returning the cdr. The function is named, presumably, to suggest what it is for: its purpose or behavior WRT DIRED AND SUBDIRS. Hard to believe that when someone goes to the trouble of spelling out in the bug report why better doc is needed here you cannot read and understand that. > However: >=20 > ;; can't use macro, must be redefinable for other alist format in > dired-nstd. > (defalias 'dired-get-subdir-min 'cdr) >=20 > Which is kinda er. >=20 > I don't know what nstd is, and the function doesn't seem to be > redefined anywhere, so is this just legacy gunk? Should > `dired-get-subdir-min' just be replaced by `cdr' in all the > calling sites? Yes, that can be the first question, if you want to get into it. If you do not want to file a separate (code) bug for that, fine. But if this function is kept then please document it properly.