helpful

commit 1c6d5cb3d86d270d1a270b248f9cc15ae0a4d831
parent 7ec5efdefed17f93e194a2b50615fbd9b38c6d4b
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Sat,  3 Jun 2017 17:45:24 +0100

Expand commentary and readme

Diffstat:
M
README.md
 | 
36
+++++++++++++++++++++++++++++++-----
M
helpful.el
 | 
13
++++++++++++-

2 files changed, 43 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
@@ -1,16 +1,42 @@
 # Helpful [![Build Status](https://travis-ci.org/Wilfred/helpful.svg?branch=master)](https://travis-ci.org/Wilfred/helpful) [![Coverage Status](https://coveralls.io/repos/github/Wilfred/helpful/badge.svg?branch=master)](https://coveralls.io/github/Wilfred/helpful?branch=master)
 
-A better Help buffer.
+Helpful is an alternative to the built-in Emacs help that provides
+much more contextual information.
 
 SCREENSHOT
 
-Helpful will:
+## Source code
 
-Always **show the source code** of functions. It shows the
+Helpful will try really hard to show the source code. It shows the
 source code for interactively defined functions (unlike the built-in
 Help) and falls back to the raw sexp if no source is available.
 
-Display **symbol properties**. This provides visibility of features
+## View Callers
+
+Helpful will show you where a function is being called!
+
+## Pretty Docstrings
+
+Helpful renders docstrings with full cross-references, hiding
+superfluous punctuation.
+
+## Symbol Properties
+
+Helpful will show you the properties that have been applied to the
+current symbol. This provides visibility of features
 like edebug or byte-code optimisation.
 
-Show **references**. You can see where a function is being called!
+## Describe Commands
+
+Helpful provides a separate `helpful-command` function, for when you
+just want to view interactive functions.
+
+## View Keymaps
+
+Helpful displays any keybindings that apply to interactive functions.
+
+## Integrated Tooling
+
+You can trace, debug or disassemble functions from inside
+Helpful. This is discoverable and doesn't require memorisation of
+commands.
diff --git a/helpful.el b/helpful.el
@@ -22,7 +22,18 @@
 
 ;;; Commentary:
 
-;; 
+;; Helpful is a replacement for *help* buffers that provides much more
+;; contextual information.  To get started, try:
+;; `M-x helpful-function RET helpful-function
+;;
+;; The full set of commands you can try is:
+;;
+;; * helpful-function
+;; * helpful-command
+;; * helpful-macro
+;;
+;; For more information and screenshots, see
+;; https://github.com/wilfred/helpful
 
 ;;; Code: