emacs: Support overriding help and describing prefix action
authorAustin Clements <amdragon@MIT.EDU>
Sun, 6 Oct 2013 03:22:46 +0000 (23:22 -0400)
committerDavid Bremner <bremner@debian.org>
Mon, 7 Oct 2013 23:31:53 +0000 (20:31 -0300)
commitfad4f21cb7016f22e496bb92e117382b969f5f09
tree5ec3d53632db4c15294b3a5db8aee02c0bbe3b04
parentadfff87a7161473a293bb57b2c178d7dbe267224
emacs: Support overriding help and describing prefix action

Traditionally, function documentation strings are intended primarily
for programmers, rather than users.  They're written from the
perspective of calling the function, not interactively invoking it.
They're only ever displayed along with the function prototype (and
often refer to argument names).  And built-in help commands like
`describe-bindings' show the name of the command, not its
documentation.

The notmuch help system is like `describe-bindings', but tries to be
more user-friendly by displaying documentation strings, rather than
Elisp command names.  For most commands, this is fine, but for some
the "programmer description" is inappropriate for interactive use.
This is particularly noticeable for commands that take an optional
prefix argument.

This patch adds support for two symbol properties: notmuch-doc and
notmuch-prefix-doc, which let a command override its interactive
documentation and provide separate documentation for its prefixed
invocation.  If notmuch-prefix-doc is present, we add an extra line to
the help giving the prefixed key sequence along with the documentation
for the prefixed command.
emacs/notmuch.el