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

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 31962 <at> debbugs.gnu.org
Subject: Re: bug#31962: 27.0; imenu.el constructs - names and doc
Date: Sat, 30 Jun 2018 12:28:24 +0300

> 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.

> 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.

Previous Next

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