bug#6756: 23.2; `describe-function' describing functions that aren't

bug#6756: 23.2; `describe-function' describing functions that aren't

[MON KEY]

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\

bug#6756: 23.2; `describe-function' describing functions that aren't

[Juanma Barranquero]

On Thu, Jul 29, 2010 at 19:22, MON KEY <monkey@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

bug#6756: 23.2; `describe-function' describing functions that aren't

[MON KEY]

On Thu, Jul 29, 2010 at 6:55 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Thu, Jul 29, 2010 at 19:22, MON KEY <monkey@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\

bug#6756: 23.2; `describe-function' describing functions that aren't

[Juanma Barranquero]

On Sat, Jul 31, 2010 at 04:50, MON KEY <monkey@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