From unknown Mon Jun 23 18:34:11 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31962: 27.0; imenu.el constructs - names and doc Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 25 Jun 2018 01:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 31962 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 31962@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.152989150121785 (code B ref -1); Mon, 25 Jun 2018 01:52:01 +0000 Received: (at submit) by debbugs.gnu.org; 25 Jun 2018 01:51:41 +0000 Received: from localhost ([127.0.0.1]:34193 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXGfM-0005fI-Sd for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:41 -0400 Received: from eggs.gnu.org ([208.118.235.92]:60614) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXGfK-0005f5-P3 for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXGfE-0005Rl-MW for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:33 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:40147) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fXGfE-0005RZ-JC for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:32 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51579) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXGfD-0005ZL-7q for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:32 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXGfA-0005PL-3v for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:31 -0400 Received: from aserp2120.oracle.com ([141.146.126.78]:42074) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fXGf9-0005OS-Sm for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:28 -0400 Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w5P1nJuA140141 for ; Mon, 25 Jun 2018 01:51:26 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=yObMRY2bcf0SpU3gggDAH8NJXbapbP4x4G3vvZBZyto=; b=Q+dfgAFu8PgtYrBwjacquq5FgGWpEMLybe1k/PWIytQ4k93HvCkTFqDj80Wlt7zJVKXc NDQ00ys+rn85xVKFs0pCenBofzVucGajIW4j1NPEDKdqAXRhHSEKdta4L4fT7O9reH8j oilBs8xVYVkBkPQgyk+8QO8MuFDtbR+7YeepipggE8ByzDZM14oMKd3t/Qq2YDSeEcTm jvIBXI6HTQPHWe+FGmMOPavlobly8UTnBywI1n/WfVabyIZn+LiM6J7cI7WJvcmZv108 aHGlAE7ANsSzlcNl3nesx0bD9Ll6thiZ6S64U3XENWWAQWfv0Ktwt1DdIyR8Caf6cwDy Jw== Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2120.oracle.com with ESMTP id 2jt7mp8ub6-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 25 Jun 2018 01:51:26 +0000 Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w5P1pP2W029458 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 25 Jun 2018 01:51:26 GMT Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w5P1pOwX023486 for ; Mon, 25 Jun 2018 01:51:25 GMT MIME-Version: 1.0 Message-ID: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4705.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8934 signatures=668703 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1806210000 definitions=main-1806250020 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) 1. `imenu--generic-function' should not have a double-hyphen in its name. It is the main function in the library, and it is explicitly referenced by multiple doc strings in the file, including that of a user option (`imenu-generic-skip-comments-and-strings') and that of the principal configuration variable (`imenu-generic-expression'), which is defined per mode. The function should be renamed to `imenu-generic-function', and the old name should be deprecated. 2. The doc string of `imenu--generic-function' says this, with zero description of INDEX-NAME INDEX-POSITION FUNCTION and ARGUMENTS: The return value is an alist of the form (INDEX-NAME . INDEX-POSITION) or (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...) The return value may also consist of nested index alists like: (INDEX-NAME . INDEX-ALIST) depending on PATTERNS. Each of those pieces of the return value should be specified, not just named. 3. Similarly, other functions and variables should be renamed to use a single, not a double, hyphen, starting with `imenu--sort-by-name' and `imenu--index-alist'. I don't argue now that NO functions wnd variables in the library should have names declaring that they are internal, but a better judgment call is in order. They too are referenced from other doc strings. For example, the doc string of `imenu-sort-function' says to look at `imenu--sort-by-name' for an example of a sort function. And the doc string of autoloaded variable `imenu-create-index-function' refers to `imenu--index-alist' for the format of the buffer index alist. We are documenting the structure and behavior of Imenu by referring to "internal" variables and functions. That makes no sense - or rather, it points out how silly was declaring these to be "internal". In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32) of 2018-03-21 Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install -C 'CFLAGS=3D-O2 -static -g3'' From unknown Mon Jun 23 18:34:11 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31962: 27.0; imenu.el constructs - names and doc Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 30 Jun 2018 09:29:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31962 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 31962@debbugs.gnu.org Received: via spool by 31962-submit@debbugs.gnu.org id=B31962.15303509052649 (code B ref 31962); Sat, 30 Jun 2018 09:29:01 +0000 Received: (at 31962) by debbugs.gnu.org; 30 Jun 2018 09:28:25 +0000 Received: from localhost ([127.0.0.1]:40346 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fZCB7-0000gf-0v for submit@debbugs.gnu.org; Sat, 30 Jun 2018 05:28:25 -0400 Received: from eggs.gnu.org ([208.118.235.92]:43739) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fZCB4-0000gS-Tu for 31962@debbugs.gnu.org; Sat, 30 Jun 2018 05:28:23 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fZCAw-0007kM-Co for 31962@debbugs.gnu.org; Sat, 30 Jun 2018 05:28:17 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:58643) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fZCAw-0007k5-8I; Sat, 30 Jun 2018 05:28:14 -0400 Received: from [176.228.60.248] (port=4297 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fZCAv-0002ss-KN; Sat, 30 Jun 2018 05:28:14 -0400 Date: Sat, 30 Jun 2018 12:28:24 +0300 Message-Id: <83po08mxmv.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> (message from Drew Adams on Sun, 24 Jun 2018 18:51:23 -0700 (PDT)) References: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.0 (------) > Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT) > From: Drew Adams > > 1. `imenu--generic-function' should not have a double-hyphen in its > name. It is the main function in the library, and it is explicitly > referenced by multiple doc strings in the file As long as this function is not autoloaded, we have no unequivocal proof that it's the main function in the library. A function that is the workhorse of a library can legitimately be an internal function. I agree that this case is somewhat borderline, but I don't have enough time and energy to make the changes in the current system, because the problems it creates sound very minor to me. I made small fixes in 2 doc strings, but that's as far as I was prepared to go in this case. > including that of a user option > (`imenu-generic-skip-comments-and-strings') and that of the > principal configuration variable (`imenu-generic-expression'), which > is defined per mode. The doc string of imenu-generic-skip-comments-and-strings was one of those I changed. > 2. The doc string of `imenu--generic-function' says this, with zero > description of INDEX-NAME INDEX-POSITION FUNCTION and ARGUMENTS: > > The return value is an alist of the form > (INDEX-NAME . INDEX-POSITION) > or > (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...) > The return value may also consist of nested index alists like: > (INDEX-NAME . INDEX-ALIST) > depending on PATTERNS. > > Each of those pieces of the return value should be specified, not just > named. Not as long as this is an internal function. > 3. Similarly, other functions and variables should be renamed to use a > single, not a double, hyphen, starting with `imenu--sort-by-name' and > `imenu--index-alist'. I don't argue now that NO functions wnd variables > in the library should have names declaring that they are internal, but a > better judgment call is in order. Likewise. > We are documenting the structure and behavior of Imenu by referring to > "internal" variables and functions. That makes no sense - or rather, it > points out how silly was declaring these to be "internal". Please don't use "silly" to describe work of others, as doing so makes the discussion much less pleasant. From unknown Mon Jun 23 18:34:11 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Drew Adams Subject: bug#31962: closed (Re: bug#31962: 27.0; imenu.el constructs - names and doc) Message-ID: References: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> X-Gnu-PR-Message: they-closed 31962 X-Gnu-PR-Package: emacs Reply-To: 31962@debbugs.gnu.org Date: Sat, 19 Oct 2019 01:10:03 +0000 Content-Type: multipart/mixed; boundary="----------=_1571447403-7789-1" This is a multi-part message in MIME format... ------------=_1571447403-7789-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #31962: 27.0; imenu.el constructs - names and doc which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 31962@debbugs.gnu.org. --=20 31962: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D31962 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1571447403-7789-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 31962-done) by debbugs.gnu.org; 19 Oct 2019 01:09:34 +0000 Received: from localhost ([127.0.0.1]:51725 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iLdFN-00020p-Mm for submit@debbugs.gnu.org; Fri, 18 Oct 2019 21:09:33 -0400 Received: from mail-pf1-f172.google.com ([209.85.210.172]:35825) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iLdFL-00020Z-CF for 31962-done@debbugs.gnu.org; Fri, 18 Oct 2019 21:09:31 -0400 Received: by mail-pf1-f172.google.com with SMTP id 205so4866948pfw.2 for <31962-done@debbugs.gnu.org>; Fri, 18 Oct 2019 18:09:31 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to:cc; bh=m5c4UzU75F8MMAalYmAYA3Mxj4AM91cW/VukXIH1oaw=; b=Xn4FI/Zbuf9mr07b5ooaOSAewoEB/qaVTbCAA3OlOfer4ORrdp/v1LZaU5d+uTeEOc 2h+4bfa3LOtpqG7ej2R27dTGH1kgRPf69INCvUDIJ8VLKab0WnyUNZ44NEjwzp8mFIiy INJqmYwrd5tMmCWXLf2F9tTJ9jrEMuXj3NypfCu8AScTe5FbXEib+nbG3UEylB11Gj8f GV3GDOOY1qyubcpQkbHKbN0M37sT2F8Yg2V+lz4TgTG0KaEexejJDMzuTd+LvoiKBqAv hkgvVPJyCTg2OXnMESEwv2u05hFtseK5Z05Ak/RKswyWH4cp7i5+oVy5YnH3XgMb8HMp 9JAw== X-Gm-Message-State: APjAAAX9oB7OqOG194yQWMbh4QFKgrIGLwYLbcvKq3/v/RGHCLCcE5RF SXEhMu3Cs9TfgZJit4df1pAZnXXGMa8ghK/R5qg= X-Google-Smtp-Source: APXvYqxkXV/gIghsQT/J1WB1nLb4Zy+W0nn91189RwSJB+0BPF12XY7lpug3mLI4dmI+Prf1UxMZ9SYbpdAyvaXftOE= X-Received: by 2002:a62:1bd3:: with SMTP id b202mr9872003pfb.50.1571447365095; Fri, 18 Oct 2019 18:09:25 -0700 (PDT) MIME-Version: 1.0 From: Stefan Kangas Date: Sat, 19 Oct 2019 03:09:14 +0200 Message-ID: Subject: Re: bug#31962: 27.0; imenu.el constructs - names and doc To: Eli Zaretskii Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.3 (/) X-Debbugs-Envelope-To: 31962-done Cc: 31962-done@debbugs.gnu.org, Drew Adams X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) Eli Zaretskii writes: >> Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT) >> From: Drew Adams >> >> 1. `imenu--generic-function' should not have a double-hyphen in its >> name. It is the main function in the library, and it is explicitly >> referenced by multiple doc strings in the file > > As long as this function is not autoloaded, we have no unequivocal > proof that it's the main function in the library. A function that is > the workhorse of a library can legitimately be an internal function. > > I agree that this case is somewhat borderline, but I don't have enough > time and energy to make the changes in the current system, because the > problems it creates sound very minor to me. > > I made small fixes in 2 doc strings, but that's as far as I was > prepared to go in this case. > >> including that of a user option >> (`imenu-generic-skip-comments-and-strings') and that of the >> principal configuration variable (`imenu-generic-expression'), which >> is defined per mode. > > The doc string of imenu-generic-skip-comments-and-strings was one of > those I changed. > >> 2. The doc string of `imenu--generic-function' says this, with zero >> description of INDEX-NAME INDEX-POSITION FUNCTION and ARGUMENTS: >> >> The return value is an alist of the form >> (INDEX-NAME . INDEX-POSITION) >> or >> (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...) >> The return value may also consist of nested index alists like: >> (INDEX-NAME . INDEX-ALIST) >> depending on PATTERNS. >> >> Each of those pieces of the return value should be specified, not just >> named. > > Not as long as this is an internal function. > >> 3. Similarly, other functions and variables should be renamed to use a >> single, not a double, hyphen, starting with `imenu--sort-by-name' and >> `imenu--index-alist'. I don't argue now that NO functions wnd variables >> in the library should have names declaring that they are internal, but a >> better judgment call is in order. > > Likewise. It looks like Eli made the necessary changes above, and I see nothing more to do here. I'm therefore closing this bug report. Please reopen if that's incorrect. Best regards, Stefan Kangas ------------=_1571447403-7789-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 25 Jun 2018 01:51:41 +0000 Received: from localhost ([127.0.0.1]:34193 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXGfM-0005fI-Sd for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:41 -0400 Received: from eggs.gnu.org ([208.118.235.92]:60614) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXGfK-0005f5-P3 for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXGfE-0005Rl-MW for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:33 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:40147) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fXGfE-0005RZ-JC for submit@debbugs.gnu.org; Sun, 24 Jun 2018 21:51:32 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51579) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXGfD-0005ZL-7q for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:32 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXGfA-0005PL-3v for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:31 -0400 Received: from aserp2120.oracle.com ([141.146.126.78]:42074) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fXGf9-0005OS-Sm for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:51:28 -0400 Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w5P1nJuA140141 for ; Mon, 25 Jun 2018 01:51:26 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=yObMRY2bcf0SpU3gggDAH8NJXbapbP4x4G3vvZBZyto=; b=Q+dfgAFu8PgtYrBwjacquq5FgGWpEMLybe1k/PWIytQ4k93HvCkTFqDj80Wlt7zJVKXc NDQ00ys+rn85xVKFs0pCenBofzVucGajIW4j1NPEDKdqAXRhHSEKdta4L4fT7O9reH8j oilBs8xVYVkBkPQgyk+8QO8MuFDtbR+7YeepipggE8ByzDZM14oMKd3t/Qq2YDSeEcTm jvIBXI6HTQPHWe+FGmMOPavlobly8UTnBywI1n/WfVabyIZn+LiM6J7cI7WJvcmZv108 aHGlAE7ANsSzlcNl3nesx0bD9Ll6thiZ6S64U3XENWWAQWfv0Ktwt1DdIyR8Caf6cwDy Jw== Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2120.oracle.com with ESMTP id 2jt7mp8ub6-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 25 Jun 2018 01:51:26 +0000 Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w5P1pP2W029458 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 25 Jun 2018 01:51:26 GMT Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w5P1pOwX023486 for ; Mon, 25 Jun 2018 01:51:25 GMT MIME-Version: 1.0 Message-ID: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 27.0; imenu.el constructs - names and doc X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4705.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8934 signatures=668703 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1806210000 definitions=main-1806250020 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) 1. `imenu--generic-function' should not have a double-hyphen in its name. It is the main function in the library, and it is explicitly referenced by multiple doc strings in the file, including that of a user option (`imenu-generic-skip-comments-and-strings') and that of the principal configuration variable (`imenu-generic-expression'), which is defined per mode. The function should be renamed to `imenu-generic-function', and the old name should be deprecated. 2. The doc string of `imenu--generic-function' says this, with zero description of INDEX-NAME INDEX-POSITION FUNCTION and ARGUMENTS: The return value is an alist of the form (INDEX-NAME . INDEX-POSITION) or (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...) The return value may also consist of nested index alists like: (INDEX-NAME . INDEX-ALIST) depending on PATTERNS. Each of those pieces of the return value should be specified, not just named. 3. Similarly, other functions and variables should be renamed to use a single, not a double, hyphen, starting with `imenu--sort-by-name' and `imenu--index-alist'. I don't argue now that NO functions wnd variables in the library should have names declaring that they are internal, but a better judgment call is in order. They too are referenced from other doc strings. For example, the doc string of `imenu-sort-function' says to look at `imenu--sort-by-name' for an example of a sort function. And the doc string of autoloaded variable `imenu-create-index-function' refers to `imenu--index-alist' for the format of the buffer index alist. We are documenting the structure and behavior of Imenu by referring to "internal" variables and functions. That makes no sense - or rather, it points out how silly was declaring these to be "internal". In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32) of 2018-03-21 Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install -C 'CFLAGS=3D-O2 -static -g3'' ------------=_1571447403-7789-1--