GNU bug report logs - #31962
27.0; imenu.el constructs - names and doc

Previous Next

Full log

Message #13 received at 31962-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31962-done <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#31962: 27.0; imenu.el constructs - names and doc
Date: Sat, 19 Oct 2019 03:09:14 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Sun, 24 Jun 2018 18:51:23 -0700 (PDT)
>> From: Drew Adams <drew.adams <at> oracle.com>
>>
>> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.