From unknown Mon Jun 23 18:29:38 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#31962 <31962@debbugs.gnu.org> To: bug#31962 <31962@debbugs.gnu.org> Subject: Status: 27.0; imenu.el constructs - names and doc Reply-To: bug#31962 <31962@debbugs.gnu.org> Date: Tue, 24 Jun 2025 01:29:38 +0000 retitle 31962 27.0; imenu.el constructs - names and doc reassign 31962 emacs submitter 31962 Drew Adams severity 31962 wishlist thanks From debbugs-submit-bounces@debbugs.gnu.org Sun Jun 24 21:51:41 2018 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'' From debbugs-submit-bounces@debbugs.gnu.org Sat Jun 30 05:28:25 2018 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 To: Drew Adams In-reply-to: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> (message from Drew Adams on Sun, 24 Jun 2018 18:51:23 -0700 (PDT)) Subject: Re: bug#31962: 27.0; imenu.el constructs - names and doc 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-Debbugs-Envelope-To: 31962 Cc: 31962@debbugs.gnu.org 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 debbugs-submit-bounces@debbugs.gnu.org Fri Oct 18 21:09:34 2019 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 From unknown Mon Jun 23 18:29:38 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 16 Nov 2019 12:24:08 +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