From monnier@iro.umontreal.ca Mon Nov 23 06:58:18 2009 Received: (at submit) by emacsbugs.donarmstrong.com; 23 Nov 2009 14:58:19 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-1.3 required=4.0 tests=AWL,FOURLA,IMPRONONCABLE_1, MURPHY_DRUGS_REL8,MURPHY_WRONG_WORD1,MURPHY_WRONG_WORD2 autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id nANEwGWP018996 for ; Mon, 23 Nov 2009 06:58:18 -0800 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NCaMq-0004Zl-M9 for bug-gnu-emacs@gnu.org; Mon, 23 Nov 2009 09:58:16 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NCaMl-0004YX-UO for bug-gnu-emacs@gnu.org; Mon, 23 Nov 2009 09:58:16 -0500 Received: from [199.232.76.173] (port=33238 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NCaMl-0004YJ-Hv for bug-gnu-emacs@gnu.org; Mon, 23 Nov 2009 09:58:11 -0500 Received: from ironport2-out.teksavvy.com ([206.248.154.183]:53065 helo=ironport2-out.pppoe.ca) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NCaMj-000751-Fx for bug-gnu-emacs@gnu.org; Mon, 23 Nov 2009 09:58:09 -0500 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AqsEANkxCkvO+IIa/2dsb2JhbACBTdQfhDwEgxmGaQ X-IronPort-AV: E=Sophos;i="4.47,272,1257138000"; d="scan'208";a="49846666" Received: from 206-248-130-26.dsl.teksavvy.com (HELO pastel.home) ([206.248.130.26]) by ironport2-out.pppoe.ca with ESMTP; 23 Nov 2009 09:58:08 -0500 Received: by pastel.home (Postfix, from userid 20848) id 8640A80E5; Mon, 23 Nov 2009 09:58:08 -0500 (EST) From: Stefan Monnier To: Toby Cubitt Cc: bug-gnu-emacs@gnu.org Subject: Re: avl-tree.el enhancements Message-ID: References: <20091123000123.GA7647@c3po> <20091123094431.GA31081@c3po> Date: Mon, 23 Nov 2009 09:58:08 -0500 In-Reply-To: <20091123094431.GA31081@c3po> (Toby Cubitt's message of "Mon, 23 Nov 2009 09:44:31 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-detected-operating-system: by monty-python.gnu.org: Genre and OS details not recognized. >> Hmm... using integers for "direction" isn't pretty. I see it mostly >> comes from its use in avl-tree--node-branch. I guess we'll have to live >> with it for now... > Exactly -- it stems from avl-tree--node-branch (which isn't my code). > The comment after its definition (also not mine) explains the reason > for it. I can't think of an efficient way to avoid this. I know. I wrote the comment ;-) >> > +(defun avl-tree--del-balance (node branch dir) >> > + ;; Rebalance a tree at the left (BRANCH=0) or right (BRANCH=1) child >> > + ;; of NODE after deleting from the left (DIR=0) or right (DIR=1) >> > + ;; sub-tree of that child [or is it vice-versa?]. Return t if the >> > + ;; height of the tree has shrunk. >> >> This comment should be a docstring instead. > I've followed the existing convention in avl-tree.el, which doesn't > provide docstrings for internal functions. If you want to change all the > comments to docstrings throughout, that's up to you, but I disagree. Maybe I'll do it at some point, but at least when changing code, the new code should use docstrings rather than comments. It used to be the case that docstrings were costly (in terms of memory use), but that was fixed around Emacs-19 so docstrings are not kept in memory any more. There is still a fair bit of code written before that time which still avoids using docstrings for that reason. While I don't think it's important to go back and fix all that old code, I think it's worthwhile to fix it when we touch such code. > I personally find the fact that internal library functions aren't > documented to be a useful form of documentation in itself: it tells me > that the function definitely shouldn't be used outside of the library. That's what the "--" is for in avl-tree--del-balance. It's also much better because you don't need to check "does this function have a docstring" to figure out whether it's internal or not. > Since Elisp doesn't have modules or private functions, that's the > closest one can get to an internal library function. Emacs abounds > with functions lacking docstrings, many of them apparently for > this reason. Some people follow this kind of convention, but the Emacs project doesn't. We only drop the docstring when we're lazy or when we don't know what to put in it. > If you still insist on making one or other or both of these into > docstrings, I'll make the necessary changes to the patches. Please do, thank you. >> Why exactly do you remove the \(fn TREE) thingy at the end? > It seemed to be a strange documentation convention followed only by > avl-tree.el, and inconsistently at that. It's redundant, and as far as I > know isn't used anywhere else in Emacs, because "C-h f " > already automatically shows the function's calling convention. It's a trick that can be used to *change* the calling convention displayed. So it's not used/needed often. But here, for example, it's used to change (avl-tree-compare-function CL-X) into (avl-tree-compare-function TREE), so the docstring (which refers to TREE) makes more sense. Sometimes it's used to hide some internal arguments. It's also used systematically in autoloaded definitions so as to provide the calling convention before the function is loaded. >> Overall, looks good. Please provide a ChangeLog entry for it as well. > Errrmmmm...do you mean a ChangeLog entry in the avl-tree.el file itself? > If so, I already did! :) No, an entry in the format used by the ChangeLog file. See http://www.gnu.org/prep/standards/standards.html#Change-Logs Stefan From rgm@gnu.org Mon Nov 23 09:14:01 2009 Received: (at control) by emacsbugs.donarmstrong.com; 23 Nov 2009 17:14:01 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.2 required=4.0 tests=AWL,ONEWORD,X_DEBBUGS_NO_ACK autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id nANHDxiC032527 for ; Mon, 23 Nov 2009 09:14:00 -0800 Received: from rgm by fencepost.gnu.org with local (Exim 4.67) (envelope-from ) id 1NCcUA-00028I-Tb; Mon, 23 Nov 2009 12:13:58 -0500 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <19210.49878.866098.678133@fencepost.gnu.org> Date: Mon, 23 Nov 2009 12:13:58 -0500 From: Glenn Morris To: control Subject: control X-Attribution: GM X-Mailer: VM (www.wonderworks.com/vm), GNU Emacs (www.gnu.org/software/emacs) X-Hue: red X-Ran: .O'-;D_0!TDb.OFgXqr|QA;I3S]42v*9ky4*b!=n(~ X-Debbugs-No-Ack: yes merge 5012 5015 5016 5021 5024 severity 5012 wishlist severity 5018 wishlist reassign 5017 spam reassign 5023 spam close 4898 From rgm@gnu.org Tue Nov 24 15:25:33 2009 Received: (at control) by emacsbugs.donarmstrong.com; 24 Nov 2009 23:25:33 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.7 required=4.0 tests=AWL,MURPHY_DRUGS_REL8,ONEWORD, VALID_BTS_CONTROL autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id nAONPWKh003549 for ; Tue, 24 Nov 2009 15:25:33 -0800 Received: from rgm by fencepost.gnu.org with local (Exim 4.67) (envelope-from ) id 1ND4lH-0003ZM-AD; Tue, 24 Nov 2009 18:25:31 -0500 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <19212.27499.290533.841289@fencepost.gnu.org> Date: Tue, 24 Nov 2009 18:25:31 -0500 From: Glenn Morris To: control Subject: control tags 4944 = close 4977 forcemerge 4977 4978 reassign 4893 emacs,ns reassign 5028 spam reassign 5034 spam reassign 5035 spam tags 5012 patch From unknown Fri Aug 15 20:52:58 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 23 Mar 2012 11:24:03 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator