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\