Hey Emacs,

Among the many ways to get information about a package (READMEs, Commentaries, manuals, menu-bar menus, and describe-mode; are there others?), describe-mode is the only universally available one. It always works, but it's not very nice to use: it just gives you a list of function names and the associated bindings.

Recently I added an extra documentation feature to one of my packages, biblio.el.  It's a single function that walks a keymap, and displays for each binding not only the name of the associated function, but also the first line of the documentation of each function. Here's how it looks in haskell-mode:

    Help with ‘haskell-mode’

    ‘C-M-q’ (prog-indent-sexp)
      Indent the expression after point.

    ‘C-c C-c’ (haskell-compile)
      Compile the Haskell program including the current buffer.

    ‘C-c C-s’ (haskell-mode-toggle-scc-at-point)
      If point is in an SCC annotation, kill the annotation.  Otherwise, try to insert a new annotation.

    ‘C-c TAB’ (haskell-process-do-info)
      Print info on the identifier at point.

    ‘C-c C-t’ (haskell-process-do-type)
      Print the type of the given expression.

    ‘C-c C-v’ (haskell-mode-enable-process-minor-mode)
      Tell the user to choose a minor mode for process interaction.

    ‘C-c C-b’, ‘C-c C-z’ (haskell-interactive-switch)
      Switch to the interactive mode for this session.

    ‘C-c C-l’ (haskell-process-load-file)
      Load the current buffer file.

    ‘C-c C-.’ (haskell-mode-format-imports)
      Format the imports by aligning and sorting them.

    ‘<remap> <delete-indentation>’ (haskell-delete-indentation)
      Like `delete-indentation' but ignoring Bird-style ">".

It's not much, but I think it looks much better. I've attached examples of the output for several other modes to this email, as well as the code used to generate this example. Contrast with the default output of C-h m for haskell-mode:

    key             binding
    ---             -------

    C-c             Prefix Command
    C-x             Prefix Command
    ESC             Prefix Command
    <remap>         Prefix Command

    <remap> <delete-indentation>    haskell-delete-indentation

    C-c C-b         haskell-interactive-switch
    C-c C-c         haskell-compile
    C-c TAB         haskell-process-do-info
    C-c C-l         haskell-process-load-file
    C-c C-s         haskell-mode-toggle-scc-at-point
    C-c C-t         haskell-process-do-type
    C-c C-v         haskell-mode-enable-process-minor-mode
    C-c C-z         haskell-interactive-switch
    C-c ESC         Prefix Command
    C-c C-.         haskell-mode-format-imports

    C-M-q           prog-indent-sexp

My implementation is rather brittle (I don't have sufficient knowledge of keymaps), but I think a documentation facility in the line of the one demoed above would be very useful.  Most interactive functions are already documented, so we'd be tapping into a large body of existing docs, making them more accessible.

What do you think? I would be happy to get help in refining this code (and this proposal). For example, we could consider hyperlinking the function names to their sources, or letting users expand the first line of the documentation to show the full docstring. We could also think about ways to cover functions that are not bound to a key by default, but which users may want to bind (e.g. by looking for interactive functions starting with the mode's name).

Cheers,
Clément.