Update history documentation

2 files changed, 39 insertions, 7 deletions

diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index 3fcd3352..dd3d3abe 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -52,7 +52,7 @@ cmd2.Cmd
         A record of previously entered commands.
 
         This attribute is an instance of :class:`cmd2.history.History`, and
-        each command is an instance of :class:`cmd2.history.HistoryItem`.
+        each command is an instance of :class:`cmd2.Statement`.
 
     .. attribute:: statement_parser
 
diff --git a/docs/features/history.rst b/docs/features/history.rst
index 56c74ed7..a1cb1233 100644
--- a/docs/features/history.rst
+++ b/docs/features/history.rst
@@ -4,14 +4,46 @@ History
 For Developers
 --------------
 
-- Describe how ``cmd2`` tracks history
-- how persistent history works
-- differences in history and bash shell history (we only store valid commands
-  in history)
-- reference the public code structures we use to store history
+The ``cmd`` module from the Python standard library includes ``readline``
+history.
+
+:class:`cmd2.Cmd` offers the same ``readline`` capabilities, but also maintains
+it's own data structures for the history of all commands entered by the user.
+When the class is initialized, it creates an instance of the
+:class:`cmd2.history.History` class (which is a subclass of ``list``) as
+:data:`cmd2.Cmd.history`.
+
+Each time a command is executed (this gets
+complex, see :ref:`features/hooks:Command Processing Loop` for exactly when)
+the parsed :class:`cmd2.Statement` is appended to :data:`cmd2.Cmd.history`.
 
 ``cmd2`` adds the option of making this history persistent via optional
-arguments to :meth:`cmd2.Cmd.__init__`.
+arguments to :meth:`cmd2.Cmd.__init__`. If you pass a filename in the
+``persistent_history_file`` argument, the contents of :data:`cmd2.Cmd.history`
+will be pickled into that history file. We chose to use pickle instead of plain
+text so that we can save the results of parsing all the commands.
+
+.. note::
+
+    ``readline`` saves everything you type, whether it is a valid command or
+    not. ``cmd2`` only saves input to internal history if the command parses
+    successfully and is a valid command. This design choice was intentional,
+    because the contents of history can be saved to a file as a script, or can
+    be re-run. Not saving invalid input reduces unintentional errors when doing
+    so.
+
+    However, this design choice causes an inconsistency between the
+    ``readline`` history and the ``cmd2`` history when you enter an invalid
+    command: it is saved to the ``readline`` history, but not to the ``cmd2``
+    history.
+
+The :data:`cmd2.Cmd.history` attribute, the :class:`cmd2.history.History`
+class, and the :class:`cmd2.history.HistoryItem` class are all part of the
+public API for :class:`cmd2.Cmd`. You could use these classes to implement
+write your own ``history`` command (see below for documentation on how the
+included ``history`` command works). If you don't like pickled history, you
+could implement your own mechanism for saving and loading history from a plain
+text file.
 
 
 For Users