From 6f03fa2cfc71ade3eed0df9a2172c180f0d53a67 Mon Sep 17 00:00:00 2001
From: Rhys Weatherley <rhys.weatherley@gmail.com>
Date: Sat, 12 Mar 2016 05:25:29 +1000
Subject: [PATCH] Shell overview documentation

---
 libraries/Terminal/Shell.cpp | 52 ++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/libraries/Terminal/Shell.cpp b/libraries/Terminal/Shell.cpp
index 8fd40463..d5ff8965 100644
--- a/libraries/Terminal/Shell.cpp
+++ b/libraries/Terminal/Shell.cpp
@@ -28,6 +28,58 @@
  * \class Shell Shell.h <Shell.h>
  * \brief Command-line shell access.
  *
+ * This class provides a command-line shell via serial ports, TCP connections,
+ * or any other type of Stream.
+ *
+ * The following example is the minimal setup for a command-line shell
+ * on a serial port.  The application calls begin() to set the underlying
+ * Stream, and periodically calls loop() to manage shell-related events.
+ *
+ * \code
+ * Shell shell;
+ *
+ * void setup() {
+ *     Serial.begin(9600);
+ *     shell.setPrompt("$ ");
+ *     shell.begin(Serial);
+ * }
+ *
+ * void loop() {
+ *     shell.loop();
+ * }
+ * \endcode
+ *
+ * Commands can be registered with the shell by the application to be
+ * invoked when the user types in the corresponding command.  Each
+ * command is associated with a handler function:
+ *
+ * \code
+ * void cmdMotor(Shell &shell, int argc, const ShellArguments &argv)
+ * {
+ *     ...
+ * }
+ *
+ * ShellCommand(motor, "Turn the motor on or off", cmdMotor);
+ * \endcode
+ *
+ * There are two standard commands built into Shell: "help" and "exit".
+ * The "help" command provides a list of all registered commands with
+ * the short help string from the ShellCommand() registration.
+ * The "exit" command logs the user out and returns to the login prompt,
+ * or stops the underlying connection in the case of TCP streams.
+ *
+ * The F1 key can be used as a synonym for "help" and CTRL-D can be used
+ * as a synonym for "exit".
+ *
+ * Shell provides some limited history editing for scrolling back through
+ * previous commands.  The size of the history stack is provided in the
+ * second argument to begin():
+ *
+ * \code
+ * shell.begin(Serial, 5);
+ * \endcode
+ *
+ * \sa Terminal
  */
 
 /**