Re: Documentation for ido-mode is not very enlightening

[era eriksson <era+gmane@iki.fi>]

martin rudalics <rudalics <at> gmx.at> writes:
>  > Here's the documentation string for the function "ido-mode":
>  >
>  >   ido-mode is a variable defined in `ido.el'.
> 
> Hmmm... This is the doc-string for the _variable_ `ido-mode'.
> Please try C-h f RET ido-mode RET instead.

Right you are.  That does not change the fundamental problem: if you don't know
what ido-mode is, it won't help you find out.

  ido-mode is an interactive autoloaded Lisp function in `ido'.
  (ido-mode &optional arg)

  Toggle ido speed-ups on or off.
  With arg, turn ido speed-up on if arg is positive, off otherwise.
  Turning on ido-mode will remap (via a minor-mode keymap) the default
  keybindings for the `find-file' and `switch-to-buffer' families of
  commands to the ido versions of these functions.
  However, if arg arg equals 'files, remap only commands for files, or
  if it equals 'buffers, remap only commands for buffer switching.
  This function also adds a hook to the minibuffer.

What's an "ido speed-up"?  What are "ido versions" of the find-file functions? 
If you are terminally curious, you might try it out, but you should not assume
your users have indefinite time and patience.  For many users, the amount of
modes and features you could try out at one point or another is overwhelming,
and those with obscure or hard-to-find features are going to go undiscovered by
most users, and waste the time of many who try them out only to find the
features are not useful to them.

Even just the following very brief introduction from the beginning of the
"Comments" section in the ido.el source would help a lot:

  Ido - interactive do - switches between buffers and opens files and
  directories with a minimum of keystrokes. 

Like I wrote in my original report, it would be even better if the entire
comments section of the source file could be turned into documentation.  It's
fairly detailed and comprehensive.

/* era */

-- 
If this were a real .signature, it would suck less.  Well, maybe not.