Doc/examples: clarify usage messages

[openocd.git] / doc / manual / primer / commands.txt

diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt
index 9efcca2e84c5b596222e85ac2d313b56338a9201..5f89d506253c07ffaab94c137d4714f9a5b186a9 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)
-               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 = "";
@@ -55,7 +55,7 @@ static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
 @endcode
 
 Of course, you may also call other macros or functions, but that extends
-beyond the scope of this tutorial on writing commands. 
+beyond the scope of this tutorial on writing commands.
 
 @section primercmdreg Command Registration
 
@@ -63,37 +63,76 @@ Before this new function can be used, it must be registered somehow.
 For a new module, registering should be done in a new function for
 the purpose, which must be called from @c openocd.c:
 @code
+
+static const struct command_registration hello_command_handlers[] = {
+       {
+               .name = "hello",
+               .mode = COMMAND_ANY,
+               .handler = handle_hello_command,
+               .help = "print a warm greeting",
+               .usage = "[name]",
+       },
+       {
+               .chain = foo_command_handlers,
+       }
+       COMMAND_REGISTRATION_DONE
+};
+
 int hello_register_commands(struct command_context_s *cmd_ctx)
 {
-       struct command_s *cmd = register_command(cmd_ctx, NULL, "hello",
-                       NULL, COMMAND_ANY, "print greetings");
-       return cmd ? ERROR_OK : -ENOMEM;
+       return register_commands(cmd_ctx, NULL, handle_command_handlers);
 }
 @endcode
 
-That's it!  The command should now be registered and avaiable to scripts.
+Note that the "usage" text should use the same EBNF that's found
+in the User's Guide:  literals in 'single quotes', sequences of
+optional parameters in [square brackets], and alternatives in
+(parentheses|with|vertical bars), and so forth.  No angle brackets.
+
+That's it!  The command should now be registered and available to scripts.
+
+@section primercmdchain Command Chaining
+
+This example also shows how to chain command handler registration, so
+your modules can "inherit" commands provided by other (sub)modules.
+Here, the hello module includes the foo commands in the same context
+that the 'hello' command will be registered.
+
+If the @c chain field had been put in the 'hello' command, then the
+@c foo module commands would be registered under it.  Indeed, that
+technique is used to define the 'foo bar' and 'foo baz' commands,
+as well as for the example drivers that use these modules.
+
+The code for the 'foo' command handlers can be found in @c hello.c.
 
 @section primercmdcode Trying These Example Commands
 
-The commands may be enabled by editing src/openocd.c and uncommenting
-the call to @c hello_register_commands and rebuilding the source tree.
+These commands have been inherited by the dummy interface, faux flash,
+and testee target drivers.  The easiest way to test these is by using the
+dummy interface.
 
-Once OpenOCD has been built with this example code, the following script
-demonstrate the abilities that the @c hello module provides:
+Once OpenOCD has been built with this example code, the following command
+demonstrates the abilities that the @c hello module provides:
 @code
-hello
-hello World
-hello {John Doe}
-hello John Doe  # error: too many arguments
+openocd -c 'interface dummy' \
+       -c 'dummy hello' \
+       -c 'dummy hello World' \
+       -c 'dummy hello {John Doe}' \
+       -c 'dummy hello John Doe'  # error: too many arguments
 @endcode
 
 If saved in @c hello.cfg, then running <code>openocd -f hello.cfg</code>
-should produce the following output before exiting:
+should produce the following output before displaying the help text and
+exiting:
 @code
 Greetings!
 Greetings, World!
 Greetings, John Doe!
-Error: ocd_hello: too many arguments
+Error: hello: too many arguments
+Runtime error, file "openocd.cfg", line 14:
+    hello: too many arguments
+dummy hello [<name>]
+      prints a warm welcome
 @endcode
 
  */