GNU bug report logs - #6756
23.2; `describe-function' describing functions that aren't

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6756 in the body.
You can then email your comments to 6756 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: MON KEY <monkey <at> sandpframing.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 23.2; `describe-function' describing functions that aren't
Date: Thu, 29 Jul 2010 13:22:22 -0400

When called interactively `describe-function' incorrectly completes on
non-existent functions with symbol-names suffixed with a `*' and
returns documentation for an equivalent non-suffixed version of
symbol-name (assuming it exists).

e.g. if the user enters "gensym*" at the `completing-read' prompt by
`describe-function' its return value is the documentation for symbol
`gensym'.

At first glance this would appear to be a DWIM type feature.
However,  I would argue that it is a bug  because:

 a) the completing-read arg PREDICATE is `fboundp' and REQUIRE-MATCH
    is t;

 b) the `*' suffixed symbol is not (neccesarily) `fboundp';

 c) the `*' suffixed symbol may not match;

 d) When there is no equivalent non `*' suffixed symbol
    `completing-read' returns "No match" e.g. if the user enters
    "blub*" at the `completing-read' and neither "blub*" nor "blub"
    are `fboundp';

 e) If the user enters any other equivalently suffixed symbol
    `completing-read' returns "No match" e.g. when the user enters the
    suffixed symbol names "gensym!", "gensym^", "gensym+", etc.  at
    the `completing-read' and none of these are `fboundp'

Note, in the examples above "gensym" is used as the base symbol-name
but this happens just as well for non CL fncns, e.g.  if the user
enters "describe-function*" at the `completing-read' prompt by
`describe-function' the return value is the documentation for symbol
`describe-function'.

Behaviour verified with 23.2 with emacs -Q

--
/s_P\

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

From: Juanma Barranquero <lekktu <at> gmail.com>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6756 <at> debbugs.gnu.org
Subject: Re: bug#6756: 23.2; `describe-function' describing functions that 
	aren't
Date: Fri, 30 Jul 2010 00:55:05 +0200

On Thu, Jul 29, 2010 at 19:22, MON KEY <monkey <at> sandpframing.com> wrote:

>  a) the completing-read arg PREDICATE is `fboundp' and REQUIRE-MATCH
>    is t;

REQUIRE-MATCH = t means that "the user is not allowed to exit unless
the input is (or completes to) an element of COLLECTION or is null."

Note the "(or completes to)". Now, completion-styles is (basic
partial-completion emacs22), and description for partial-completion is

  Completion of multiple words, each one taken as a prefix.
  [...etc etc...]
  Additionally the user can use the char "*" as a glob pattern.

So it seems to be working as expected: describe-function* completes to
an element of COLLECTION according to the partial-completion style.

If you try remove partial-completion from completion-styles you'll get
the behavior you want.

    Juanma

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

From: MON KEY <monkey <at> sandpframing.com>
To: 6756 <at> debbugs.gnu.org
Subject: Re: bug#6756: 23.2; `describe-function' describing functions that 
	aren't
Date: Fri, 30 Jul 2010 22:50:04 -0400

On Thu, Jul 29, 2010 at 6:55 PM, Juanma Barranquero <lekktu <at> gmail.com> wrote:
> On Thu, Jul 29, 2010 at 19:22, MON KEY <monkey <at> sandpframing.com> wrote:

> If you try remove partial-completion from completion-styles you'll get
> the behavior you want.
>

Thanks for the heads up. I'm quite sure I would never have found this
information without your explicit pointer.

> So it seems to be working as expected: describe-function* completes to
> an element of COLLECTION according to the partial-completion style.
>

It would be working as expected assuming I could ascertain _what_ to
expect.

The docstring of `completing-read' should make mention of affecting
vars.

When stuff like this changes or is spread across multiple vars, fncns,
and primitives and ample xrefs in the docstrings are not provided I
find it virtually impossible to glean help from *Help*.

The vars `completion-styles' and `completion-styles-alist'
impact the behavior of (at min.) the following completion routines:
`completing-read'
`completion-try-completion'
`completion-all-completions'
`try-completion'
`all-completions'

yet none of the docs for these fncns make mention by xref to the
affecting variables... though it is doubtful that an interested user
would find much of use were she to find them by accident.

C-h v `completion-styles' tells me:
,----
|
| completion-styles is a variable defined in `minibuffer.el'.
| Its value is
| (basic partial-completion emacs22)
|
| List of completion styles to use.
| The available styles are listed in `completion-styles-alist'.
|
| { ... Boilerplate customize and version history here ... }
|
`----

C-h v `completion-styles-alist' yields this heap of un-parseable
verbosity:
,----
| {... Big 5 elt list each with 4 elts (including multi-lined
|      unreadable quoted lisp strings) ... }
|
| Documentation:
| List of available completion styles.
| Each element has the form (NAME TRY-COMPLETION ALL-COMPLETIONS DOC):
|
| { ... Form enumeration here ... }
|
`----

FWIW I increasingly find it unreasonable that *Help* defaults to
_just_ pointing the user to `customize'. Why would I bother dropping
into the miasma that is Custom when the docstring in *Help* can't be
bothered to give a reasonably coherent explanation of _what_ I should
customize and _why_ i should do so?

*Help* needs Help.

It isn't all that helpful that *Help* seems to increasingly
(implicitly) suggest dropping into *Info* or custom to get help.

>     Juanma

--
/s_P\

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

From: Juanma Barranquero <lekktu <at> gmail.com>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 6756-done <at> debbugs.gnu.org
Subject: Re: bug#6756: 23.2; `describe-function' describing functions that 
	aren't
Date: Sat, 31 Jul 2010 14:05:14 +0200

On Sat, Jul 31, 2010 at 04:50, MON KEY <monkey <at> sandpframing.com> wrote:

> It would be working as expected assuming I could ascertain _what_ to
> expect.

I agree that completion is complex and perhaps underdocumented.

> FWIW I increasingly find it unreasonable that *Help* defaults to
> _just_ pointing the user to `customize'.

I haven't noticed that. I share your opinion on Customize, though.

> It isn't all that helpful that *Help* seems to increasingly
> (implicitly) suggest dropping into *Info* or custom to get help.

I think suggesting to read Info is reasonable. It does not make much
sense to duplicate in docstrings all the information already available
on the Info pages.

I'm closing this bug, as it is no longer about describe-function
failing. Feel free to file bugs about documentation shortcomings, etc.

    Juanma

Previous Next

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