From: Zachary T Welch <zw@superlucidity.net>
Date: Tue, 17 Nov 2009 13:38:17 +0000 (-0800)
Subject: update command_handler documentation
X-Git-Tag: v0.4.0-rc1~524
X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=commitdiff_plain;h=789d47c18097abb5ee6cc8544e0ba030000fd418

update command_handler documentation

Improve the developer manual and primer sections which talk about
writing command handlers.  Notably, it documents the new CMD_* macros.
---

diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt
index 247d7b42bc..e7454b6980 100644
--- a/doc/manual/helper.txt
+++ b/doc/manual/helper.txt
@@ -45,16 +45,16 @@ another layer of handlers.
 
 @subsection helpercmdhandlerdef Defining and Calling Command Handlers
 
-These functions should be defined using the COMMAND_HANDLER macro.
+These functions should be defined using the @c COMMAND_HANDLER macro.
 These methods must be defined as static, as their principle entry point
 should be the run_command dispatch mechanism.
 
 Command helper functions that require access to the full set of
-parameters should be defined using the COMMAND_HELPER.  These must be
+parameters should be defined using the @c COMMAND_HELPER.  These must be
 declared static by you, as sometimes you might want to share a helper
-among several files (e.g. s3c24xx_nand.h).
+among several files (e.g. @c s3c24xx_nand.h).
 
-Both types of routines must be called using the CALL_COMMAND_HANDLER macro.
+Both types of routines must be called using the @c CALL_COMMAND_HANDLER macro.
 Calls using this macro to normal handlers require the name of the command
 handler (which can a name or function pointer).  Calls to helpers and
 derived handlers must pass those extra parameters specified by their
@@ -67,22 +67,18 @@ will be able to use direct invocations.
 Thus, the following macros can be used to define and call command
 handlers or helpers:
 
-- COMMAND_HANDLER - declare or define a command handler.
-- COMMAND_HELPER - declare or define a derived command handler or helper.
-- CALL_COMMAND_COMMAND - call a command handler/helper.
-
-@subsection helpercmdhandlerparam Command Handler Parameters
-
-The following parameters are defined in the scope of all command
-handlers and helpers:
-- <code>struct command_context *cmd_ctx</code> - the command's context
-- <code>unsigned argc</code> - the number of command arguments
-- <code>const char *args[]</code> - contains the command arguments
+- @c COMMAND_HANDLER - declare or define a command handler.
+- @c COMMAND_HELPER - declare or define a derived command handler or helper.
+- @c CALL_COMMAND_COMMAND - call a command handler/helper.
 
 @subsection helpercmdhandlermacros Command Handler Macros
 
-In addition, the following macro may be used:
-- <code>COMMAND_NAME</code> - contains the command name
+In addition, the following macros may be used in the context of
+command handlers and helpers:
+- @c CMD_CTX - the current @c command_context
+- @c CMD_NAME - invoked command name
+- @c CMD_ARGC - the number of command arguments
+- @c CMD_ARGV - array of command argument strings
 
 @section helpercmdprimer Command Development Primer
 
diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt
index 9efcca2e84..b15f669756 100644
--- a/doc/manual/primer/commands.txt
+++ b/doc/manual/primer/commands.txt
@@ -16,7 +16,7 @@ COMMAND_HANDLER(handle_hello_command)
 	const char *sep, *name;
 	int retval = CALL_COMMAND_HANDLER(handle_hello_args);
 	if (ERROR_OK == retval)
-		command_print(cmd_ctx, "Greetings%s%s!", sep, name);
+		command_print(CMD_CTX, "Greetings%s%s!", sep, name);
 	return retval;
 }
 @endcode
@@ -39,13 +39,13 @@ static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
 {
 	if (argc > 1)
 	{
-		LOG_ERROR("%s: too many arguments", COMMAND_NAME);
+		LOG_ERROR("%s: too many arguments", CMD_NAME);
 		return ERROR_COMMAND_SYNTAX_ERROR;
 	}
-	if (1 == argc)
+	if (1 == CMD_ARGC)
 	{
 		*sep = ", ";
-		*name = args[0];
+		*name = CMD_ARGV[0];
 	}
 	else
 		*sep = *name = "";
@@ -96,4 +96,9 @@ Greetings, John Doe!
 Error: ocd_hello: too many arguments
 @endcode
 
+This difference between the registered and displayed command name comes from
+the fact that the TCL scripts are provided with a stub that calls the munged
+name.  This stub wraps the internal <code>ocd_</code>-prefixed routine,
+providing a measure of high-level error handling.
+
  */