GNU bug report logs - #8285
24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8285 <at> debbugs.gnu.org
Subject: Re: bug#8285: 24.0.50;
	doc of `imenu-generic-expression' and `imenu--generic-function'
Date: Fri, 18 Mar 2011 20:22:46 +0200

> From: "Drew Adams" <drew.adams <at> 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.

Previous Next

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