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#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function' Date: Fri, 18 Mar 2011 11:56:38 -0700 Message-ID: <703782B6511042C395D1CD2BB6E97E2C@us.oracle.com> References: <6CAA58C0292943D68651BC3DB49A62C0@us.oracle.com> <838vwcs2yx.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1300475237 4342 80.91.229.12 (18 Mar 2011 19:07:17 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 18 Mar 2011 19:07:17 +0000 (UTC) Cc: 8285@debbugs.gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Mar 18 20:07:10 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Q0f0v-0003rN-Q4 for geb-bug-gnu-emacs@m.gmane.org; Fri, 18 Mar 2011 20:07:10 +0100 Original-Received: from localhost ([127.0.0.1]:53725 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q0f0u-0006Gb-JJ for geb-bug-gnu-emacs@m.gmane.org; Fri, 18 Mar 2011 15:07:08 -0400 Original-Received: from [140.186.70.92] (port=34081 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q0f0p-0006GS-0R for bug-gnu-emacs@gnu.org; Fri, 18 Mar 2011 15:07:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Q0f0n-0004Sk-Tw for bug-gnu-emacs@gnu.org; Fri, 18 Mar 2011 15:07:02 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:38634) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Q0f0n-0004SV-Pg for bug-gnu-emacs@gnu.org; Fri, 18 Mar 2011 15:07:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1Q0er8-0007Lf-HY; Fri, 18 Mar 2011 14:57:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 18 Mar 2011 18:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 8285 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 8285-submit@debbugs.gnu.org id=B8285.130047461028228 (code B ref 8285); Fri, 18 Mar 2011 18:57:02 +0000 Original-Received: (at 8285) by debbugs.gnu.org; 18 Mar 2011 18:56:50 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q0eqv-0007LF-8T for submit@debbugs.gnu.org; Fri, 18 Mar 2011 14:56:49 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Q0eqt-0007L3-2Q for 8285@debbugs.gnu.org; Fri, 18 Mar 2011 14:56:47 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p2IIudmT018557 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 18 Mar 2011 18:56:41 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id p2IIucV1031531 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 18 Mar 2011 18:56:38 GMT Original-Received: from abhmt020.oracle.com (abhmt020.oracle.com [141.146.116.29]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p2IIubu4023413; Fri, 18 Mar 2011 13:56:38 -0500 Original-Received: from dradamslap1 (/10.159.39.7) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 18 Mar 2011 11:56:37 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <838vwcs2yx.fsf@gnu.org> Thread-Index: AcvlmXs0XcNq6jAETvaNbYK+cKKD9QAAZuYg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 X-Source-IP: acsmt358.oracle.com [141.146.40.158] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4D83AAE7.003E,ss=1,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 18 Mar 2011 14:57:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:45154 Archived-At: > > If you don't understand the problem, change these names to UU, VV, > > WW, XX, YY, and ZZ, and see if you understand the doc. > > This argument is bogus: names of symbols can and should bear > significant semantic information that helps to understand their roles, > and if that information is descriptive enough, there's no need for any > further definitions. This doc is bogus. Using good names helps - always. It is typically not sufficient, including in this case. > As an extreme example, consider: > (defun call-func (function &rest arguments) > "Call FUNCTION with ARGUMENTS." Sorry, not interested in your "extreme example". Speak to the specific case reported, please. The meanings of the names I cited are _not_ self-evident. > I see no need to explain the arguments in this example. Which example? Yours? Agreed. But irrelevant. Or the example reported in this bug report? This report is not immediately about explaining the argument to `imenu--generic-function'. That argument, PATTERNS, _is_ described. But it is described in terms of undefined terms, so it is not described well enough. It is the explanations of those terms that are missing, not a description of the argument, PATTERNS. > I'm not saying that the doc string in question could not use some > improvement. But since imenu is about creating indices of functions > in a program source file, Oh no it is NOT. Imenu is used for indexing _lots_ of things besides just functions: variables, types, keys,... Nearly anything you want, in fact. > at least FUNCTION and ARGUMENTS do not need > any further explanations, IMO. If their meanings are obvious to you then surely you can explain what they are. Please add the explanation to the doc string so the rest of us can understand. What are they? Sure, from their names one can understand that they refer to some function and some arguments (maybe even arguments to function FUNCTION), respectively. But which function? Which arguments to which function? What's more (forgot to mention), we see this: "with FUNCTION and ARGUMENTS copied from PATTERNS" as the explanation (!) of these two terms. PATTERNS is the argument to `imenu--generic-function'. But how are FUNCTION and ARGUMENTS "copied" from PATTERNS? What does that even mean? The doc already describes the elements of alist PATTERNS, and FUNCTION and ARGUMENTS occur inside one type of element. How are they "copied" from PATTERNS? None of the terms I mentioned are explained. The meanings of none of them are clear based only on their names.