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 247d7b42bcc780570054228f9d188566d0430985..e7454b6980536a3a82ea008b3eeddce79480dcdb 100644 (file)
--- 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
 
 
 @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
 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
 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
 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:
 
 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
 
 
 @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
 
 
 @section helpercmdprimer Command Development Primer
 

diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt
index 9efcca2e84c5b596222e85ac2d313b56338a9201..b15f6697562123b3da8f6142e42df59b297bb9e7 100644 (file)
--- 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)
        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
        return retval;
 }
 @endcode


@@ -39,13 +39,13 @@ static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
 {
        if (argc > 1)
        {
 {
        if (argc > 1)
        {

-               LOG_ERROR("%s: too many arguments", COMMAND_NAME);
+               LOG_ERROR("%s: too many arguments", CMD_NAME);

                return ERROR_COMMAND_SYNTAX_ERROR;
        }
                return ERROR_COMMAND_SYNTAX_ERROR;
        }

-       if (1 == argc)
+       if (1 == CMD_ARGC)

        {
                *sep = ", ";
        {
                *sep = ", ";

-               *name = args[0];
+               *name = CMD_ARGV[0];

        }
        else
                *sep = *name = "";
        }
        else
                *sep = *name = "";


@@ -96,4 +96,9 @@ Greetings, John Doe!
 Error: ocd_hello: too many arguments
 @endcode
 
 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.
+

  */
  */