Add more documentation to the Menu class.

git-svn-id: https://arducopter.googlecode.com/svn/trunk@569 f9c3cf11-9bcb-44bc-f272-b75c42450872

libraries/AP_Common/include/menu.h

@@ -2,6 +2,17 @@
 
 /// @file	menu.h
 /// @brief	Simple commandline menu subsystem.
+/// @discussion
+/// The Menu class implements a simple CLI that accepts commands typed by
+/// the user, and passes the arguments to those commands to a function
+/// defined as handing the command.
+///
+/// Commands are defined in an array of Menu::command structures passed
+/// to the constructor.  Each entry in the array defines one command.
+///
+/// Arguments passed to the handler function are pre-converted to both
+/// long and float for convenience.
+///
 
 #define MENU_COMMANDLINE_MAX	32	///< maximum input line length
 #define MENU_ARGS_MAX			4	///< maximum number of arguments
@@ -11,6 +22,14 @@
 class Menu {
 public:
 	/// argument passed to a menu function
+	///
+	/// Space-delimited arguments are parsed from the commandline and
+	/// separated into these structures.
+	///
+	/// If the argument cannot be parsed as a float or a long, the value
+	/// of f or i respectively is undefined.  You should range-check 
+	/// the inputs to your function.
+	///
 	struct arg {
 		const char	*str;			///< string form of the argument
 		long		i;				///< integer form of the argument (if a number)
@@ -19,36 +38,58 @@ public:
 
 	/// menu command function
 	///
+	/// Functions called by menu array entries are expected to be of this
+	/// type.
+	///
+	/// @param	argc		The number of valid arguments, including the
+	///						name of the command in argv[0].  Will never be
+	///						more than MENU_ARGS_MAX.
+	/// @param	argv		Pointer to an array of Menu::arg structures
+	///						detailing any optional arguments given to the
+	///						command.  argv[0] is always the name of the
+	///						command, so that the same function can be used
+	///						to handle more than one command.
+	///
 	typedef int8_t			(*func)(uint8_t argc, const struct arg *argv);
 
 	/// menu pre-prompt function
 	///
+	/// Called immediately before waiting for the user to type a command; can be
+	/// used to display help text or status, for example.
+	///
 	/// If this function returns false, the menu exits.
+	///
 	typedef bool			(*preprompt)(void);
 	
 	/// menu command description
 	///
-	/// Note that the array of menu commands is expected to be in program 
-	/// memory.
 	struct command {
 		/// Name of the command, as typed or received.
 		/// Command names are limited in size to keep this structure compact.
+		///
 		const char	command[MENU_COMMAND_MAX];
 
 		/// The function to call when the command is received.
-		/// The \a argc argument will be at least 1, and no more than
+		///
+		/// The argc argument will be at least 1, and no more than
 		/// MENU_ARGS_MAX.  The argv array will be populated with
 		/// arguments typed/received up to MENU_ARGS_MAX.  The command
 		/// name will always be in argv[0].
+		///
 		/// Commands may return -2 to cause the menu itself to exit.
-		/// The "?", "help" and "exit" commands are always defined.
+		/// The "?", "help" and "exit" commands are always defined, but
+		/// can be overridden by explicit entries in the command array.
+		///
 		int8_t			(*func)(uint8_t argc, const struct arg *argv);	///< callback function
 	};
 
 	/// constructor
 	///
+	/// Note that you should normally not call the constructor directly.  Use
+	/// the MENU and MENU2 macros defined below.
+	///
 	/// @param prompt		The prompt to be displayed with this menu.
-	/// @param commands		An array of ::command structures.
+	/// @param commands		An array of ::command structures in program memory (PROGMEM).
 	/// @param entries		The number of entries in the menu.
 	///
 	Menu(const char *prompt, const struct command *commands, uint8_t entries, preprompt ppfunc = 0);
@@ -57,7 +98,7 @@ public:
 	void				run(void);
 	
 private:
-	/// Implements the default 'help' command
+	/// Implements the default 'help' command.
 	///
 	void				_help(void);					///< implements the 'help' command
 
@@ -79,6 +120,10 @@ private:
 
 /// Macros used to define a menu.
 ///
+/// The commands argument should be an arary of Menu::command structures, one
+/// per command name.  The array does not need to be terminated with any special
+/// record.
+///
 /// Use name.run() to run the menu.
 ///
 /// The MENU2 macro supports the optional pre-prompt printing function.
@@ -90,4 +135,4 @@ private:
 #define MENU2(name, prompt, commands, preprompt)				\
 	static const char __menu_name__ ##name[] PROGMEM = prompt;	\
 	static Menu name(__menu_name__ ##name, commands, sizeof(commands) / sizeof(commands[0]), preprompt)
-	
+