bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Drew Adams]

1. In the doc string of `imenu--generic-function', these terms are
completely undefined and unexplained: POSITION-MARKER, INDEX-NAME,
FUNCTION, ARGUMENTS, INDEX-POSITION, and INDEX-ALIST.  Please
define/explain these undefined terms.  If you don't understand the
problem, change these names to UU, VV, WW, XX, YY, and ZZ, and see if
you understand the doc.
 
2. Seems a bit odd that this internal-only function (judging by its
name, which contains `--') has all of the important doc for
`imenu-generic-expression'.  In the past, the latter's doc string
described the format.  Now the format is described (only) in the doc
string of an internal function.  This state, which seems inappropriate,
was introduced in Emacs 22.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-03-07 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Drew Adams]

Even worse: In emacs -Q, `C-h v imenu-generic-expression' shows you the
variable's doc, but that just refers you to `imenu--generic-function' (see
original bug report).  And that function has not been loaded, so (a) its name is
not linked to any doc and (2) `C-h f' does not accept its name.  Result, `C-h v
imenu-generic-expression' gives you no info about the format of the variable
value.

bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 18 Mar 2011 09:09:47 -0700
> Cc: 
> 
> If you don't understand the problem, change these names to UU, VV,
> WW, XX, YY, and ZZ, and see if you understand the doc.

This argument is bogus: names of symbols can and should bear
significant semantic information that helps to understand their roles,
and if that information is descriptive enough, there's no need for any
further definitions.

As an extreme example, consider:

 (defun call-func (function &rest arguments)
   "Call FUNCTION with ARGUMENTS."

I see no need to explain the arguments in this example.

I'm not saying that the doc string in question could not use some
improvement.  But since imenu is about creating indices of functions
in a program source file, at least FUNCTION and ARGUMENTS do not need
any further explanations, IMO.

bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Drew Adams]

> > If you don't understand the problem, change these names to UU, VV,
> > WW, XX, YY, and ZZ, and see if you understand the doc.
> 
> This argument is bogus: names of symbols can and should bear
> significant semantic information that helps to understand their roles,
> and if that information is descriptive enough, there's no need for any
> further definitions.

This doc is bogus.  Using good names helps - always.  It is typically not
sufficient, including in this case.

> As an extreme example, consider:
>  (defun call-func (function &rest arguments)
>    "Call FUNCTION with ARGUMENTS."

Sorry, not interested in your "extreme example".  Speak to the specific case
reported, please.  The meanings of the names I cited are _not_ self-evident.

> I see no need to explain the arguments in this example.

Which example?  Yours?  Agreed.  But irrelevant.
Or the example reported in this bug report?

This report is not immediately about explaining the argument to
`imenu--generic-function'.  That argument, PATTERNS, _is_ described.

But it is described in terms of undefined terms, so it is not described well
enough.  It is the explanations of those terms that are missing, not a
description of the argument, PATTERNS.

> I'm not saying that the doc string in question could not use some
> improvement.  But since imenu is about creating indices of functions
> in a program source file,

Oh no it is NOT.  Imenu is used for indexing _lots_ of things besides just
functions: variables, types, keys,...  Nearly anything you want, in fact.

> at least FUNCTION and ARGUMENTS do not need
> any further explanations, IMO.

If their meanings are obvious to you then surely you can explain what they are.
Please add the explanation to the doc string so the rest of us can understand.

What are they?  Sure, from their names one can understand that they refer to
some function and some arguments (maybe even arguments to function FUNCTION),
respectively.  But which function?  Which arguments to which function?

What's more (forgot to mention), we see this: "with FUNCTION and ARGUMENTS
copied from PATTERNS" as the explanation (!) of these two terms.  PATTERNS is
the argument to `imenu--generic-function'.

But how are FUNCTION and ARGUMENTS "copied" from PATTERNS?  What does that even
mean?  The doc already describes the elements of alist PATTERNS, and FUNCTION
and ARGUMENTS occur inside one type of element.  How are they "copied" from
PATTERNS?

None of the terms I mentioned are explained.  The meanings of none of them are
clear based only on their names.

bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. In the doc string of `imenu--generic-function', these terms are
> completely undefined and unexplained: POSITION-MARKER, INDEX-NAME,
> FUNCTION, ARGUMENTS, INDEX-POSITION, and INDEX-ALIST.  Please
> define/explain these undefined terms.

Eli answered this one...

> 2. Seems a bit odd that this internal-only function (judging by its
> name, which contains `--') has all of the important doc for
> `imenu-generic-expression'.  In the past, the latter's doc string
> described the format.  Now the format is described (only) in the doc
> string of an internal function.  This state, which seems inappropriate,
> was introduced in Emacs 22.

This was fixed in:

commit b7ccbdc2e39ff834a03a7f30516b71cd98e84a44
Author:     Chong Yidong <cyd@gnu.org>
AuthorDate: Sun Aug 5 22:14:54 2012 +0800

So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no