From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31962: 27.0; imenu.el constructs - names and doc Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT) Message-ID: <21dc18b7-5951-431b-940b-ab7e56bf8226@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1529891411 15166 195.159.176.226 (25 Jun 2018 01:50:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 25 Jun 2018 01:50:11 +0000 (UTC) To: 31962@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jun 25 03:50:07 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXGdq-0003k0-He for geb-bug-gnu-emacs@m.gmane.org; Mon, 25 Jun 2018 03:50:06 +0200 Original-Received: from localhost ([::1]:43783 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXGfs-0005cN-Nq for geb-bug-gnu-emacs@m.gmane.org; Sun, 24 Jun 2018 21:52:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51613) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXGfl-0005cE-Fm for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:52:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXGfi-0005oi-93 for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:52:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:54529) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fXGfi-0005oT-4g for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:52:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fXGfh-0005fv-SQ for bug-gnu-emacs@gnu.org; Sun, 24 Jun 2018 21:52:01 -0400 X-Loop: help-debbugs@gnu.org 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: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.152989150121785 (code B ref -1); Mon, 25 Jun 2018 01:52:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 25 Jun 2018 01:51:41 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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== Original-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 Original-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 Original-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 X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4705.0 (x86)] 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:147802 Archived-At: 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''