src/server: usage/help/doc updates

Make "usage" messages use the same EBNF as the User's Guide;
no angle brackets.  Improve and correct various helptexts.

Specifically for the port commands, clarify that the number
is optional, and omitting it causes the current number to be
displayed.

Don't use "&function"; a function's name is its address.
Remove a couple instances of pointless whitespace; shrink a
few overlong lines.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 3adc33a30aa22391d2247e0c9f559a1349aaab06..47951c6d777393d1dd396bbb007a393d48765c2e 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1721,17 +1721,17 @@ In such cases, just specify the relevant port number as zero.
 If you disable all access through TCP/IP, you will need to
 use the command line @option{-pipe} option.
 
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
 @cindex GDB server
 Specify or query the first port used for incoming GDB connections.
 The GDB port for the
 first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
 When not specified during the configuration stage,
 the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
+When specified as zero, GDB remote access ports are not activated.
 @end deffn
 
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
 Specify or query the port used for a simplified RPC
 connection that can be used by clients to issue TCL commands and get the
 output from the Tcl engine.
@@ -1741,7 +1741,7 @@ the port @var{number} defaults to 6666.
 When specified as zero, this port is not activated.
 @end deffn
 
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
 Specify or query the
 port on which to listen for incoming telnet connections.
 This port is intended for interaction with one human through TCL commands.

diff --git a/src/server/gdb_server.c b/src/server/gdb_server.c
index 96b9dbf1f730189c56d0997c099fdf0371a519db..08daa68a945acba10f88272b76fd2a553566a09e 100644 (file)
--- a/src/server/gdb_server.c
+++ b/src/server/gdb_server.c
@@ -2412,7 +2412,7 @@ COMMAND_HANDLER(handle_gdb_breakpoint_override_command)
 static const struct command_registration gdb_command_handlers[] = {
        {
                .name = "gdb_sync",
-               .handler = &handle_gdb_sync_command,
+               .handler = handle_gdb_sync_command,
                .mode = COMMAND_ANY,
                .help = "next stepi will return immediately allowing "
                        "GDB to fetch register state without affecting "
@@ -2420,40 +2420,41 @@ static const struct command_registration gdb_command_handlers[] = {
        },
        {
                .name = "gdb_port",
-               .handler = &handle_gdb_port_command,
+               .handler = handle_gdb_port_command,
                .mode = COMMAND_ANY,
-               .help = "daemon configuration command gdb_port. No arguments reports "
-                               "GDB port.",
-               .usage = "<port>",
+               .help = "Display or specify base port on which to listen "
+                       "for incoming GDB connections.  "
+                       "No arguments reports GDB port; zero disables.",
+               .usage = "[port_num]",
        },
        {
                .name = "gdb_memory_map",
-               .handler = &handle_gdb_memory_map_command,
+               .handler = handle_gdb_memory_map_command,
                .mode = COMMAND_CONFIG,
                .help = "enable or disable memory map",
-               .usage = "enable|disable"
+               .usage = "('enable'|'disable')"
        },
        {
                .name = "gdb_flash_program",
-               .handler = &handle_gdb_flash_program_command,
+               .handler = handle_gdb_flash_program_command,
                .mode = COMMAND_CONFIG,
                .help = "enable or disable flash program",
-               .usage = "enable|disable"
+               .usage = "('enable'|'disable')"
        },
        {
                .name = "gdb_report_data_abort",
-               .handler = &handle_gdb_report_data_abort_command,
+               .handler = handle_gdb_report_data_abort_command,
                .mode = COMMAND_CONFIG,
                .help = "enable or disable reporting data aborts",
-               .usage = "enable|disable"
+               .usage = "('enable'|'disable')"
        },
        {
                .name = "gdb_breakpoint_override",
-               .handler = &handle_gdb_breakpoint_override_command,
+               .handler = handle_gdb_breakpoint_override_command,
                .mode = COMMAND_EXEC,
-               .help = "force type of breakpoint "
-                       "used by gdb 'break' commands.",
-               .usage = "hard|soft|disable",
+               .help = "Display or specify type of breakpoint "
+                       "to be used by gdb 'break' commands.",
+               .usage = "('hard'|'soft'|'disable')"
        },
        COMMAND_REGISTRATION_DONE
 };

diff --git a/src/server/httpd.c b/src/server/httpd.c
index 9554ff0e40264800e534c77fca551aaafc0459b1..af8c3c8bb5f7097b403b498591f485c26599b78f 100644 (file)
--- a/src/server/httpd.c
+++ b/src/server/httpd.c
@@ -118,11 +118,11 @@ static int httpd_Jim_Command_writeform(Jim_Interp *interp, int argc,
        // Find length
        const char *data;
        int actual;
-
        int retcode;
-
-       const char *script = alloc_printf("set dummy_val $httppostdata(%s); set dummy_val",
+       const char *script = alloc_printf(
+                       "set dummy_val $httppostdata(%s); set dummy_val",
                        name);
+
        retcode = Jim_Eval_Named(interp, script, __FILE__, __LINE__);
        free((void *) script);
        if (retcode != JIM_OK)
@@ -154,27 +154,25 @@ httpd_Jim_Command_formfetch(Jim_Interp *interp,
                                    int argc,
                                    Jim_Obj *const *argv)
 {
-    if (argc != 2)
-    {
-        Jim_WrongNumArgs(interp, 1, argv, "method ?CMD_ARGV ...?");
-        return JIM_ERR;
-    }
-    char *name = (char*)Jim_GetString(argv[1], NULL);
-
-
-    const char *script = alloc_printf("set dummy_val $httppostdata(%s); set dummy_val",
-                       name);
-       int retcode = Jim_Eval_Named(interp, script, __FILE__, __LINE__);
-       free((void *) script);
-       if (retcode != JIM_OK)
-       {
-           Jim_SetResult(interp, Jim_NewEmptyStringObj(interp));
-       } else
-       {
-           Jim_SetResult(interp, Jim_GetResult(interp));
-       }
-
-    return JIM_OK;
+       if (argc != 2)
+       {
+               Jim_WrongNumArgs(interp, 1, argv, "method ?CMD_ARGV ...?");
+               return JIM_ERR;
+       }
+
+       char *name = (char*)Jim_GetString(argv[1], NULL);
+       const char *script = alloc_printf(
+               "set dummy_val $httppostdata(%s); set dummy_val",
+               name);
+       int retcode = Jim_Eval_Named(interp, script, __FILE__, __LINE__);
+
+       free((void *) script);
+       if (retcode != JIM_OK)
+               Jim_SetResult(interp, Jim_NewEmptyStringObj(interp));
+       else
+               Jim_SetResult(interp, Jim_GetResult(interp));
+
+       return JIM_OK;
 }
 
 struct httpd_request
@@ -467,16 +465,16 @@ static struct MHD_Daemon * d;
 static const struct command_registration httpd_command_handlers[] = {
        {
                .name = "formfetch",
-               .jim_handler = &httpd_Jim_Command_formfetch,
+               .jim_handler = httpd_Jim_Command_formfetch,
                .mode = COMMAND_EXEC,
-               .usage = "<parameter_name>",
+               .usage = "parameter_name",
                .help = "Reads a posted form value.",
        },
        {
                .name = "writeform",
-               .jim_handler = &httpd_Jim_Command_writeform,
+               .jim_handler = httpd_Jim_Command_writeform,
                .mode = COMMAND_EXEC,
-               .usage = "<parameter_name> <file>",
+               .usage = "parameter_name filename",
                .help = "Writes a form value to a file.",
        },
        COMMAND_REGISTRATION_DONE

diff --git a/src/server/tcl_server.c b/src/server/tcl_server.c
index a772c0aca6d32ae0266d3a3717df9aceb6f92eaa..a88c4365268f613b06ee63e7734bc5da4cea8062 100644 (file)
--- a/src/server/tcl_server.c
+++ b/src/server/tcl_server.c
@@ -181,11 +181,12 @@ COMMAND_HANDLER(handle_tcl_port_command)
 static const struct command_registration tcl_command_handlers[] = {
        {
                .name = "tcl_port",
-               .handler = &handle_tcl_port_command,
+               .handler = handle_tcl_port_command,
                .mode = COMMAND_CONFIG,
-               .help = "port on which to listen "
-                       "for incoming TCL syntax",
-               .usage = "<port>",
+               .help = "Specify port on which to listen "
+                       "for incoming Tcl syntax.  "
+                       "No arguments reports Tcl port; zero disables.",
+               .usage = "[port_num]",
        },
        COMMAND_REGISTRATION_DONE
 };

diff --git a/src/server/telnet_server.c b/src/server/telnet_server.c
index 92e7480b93e3a40b865324c64af0e6cab565b126..6f26f0ac3ca29fee55a276ade1e5cec26809c15b 100644 (file)
--- a/src/server/telnet_server.c
+++ b/src/server/telnet_server.c
@@ -619,17 +619,18 @@ COMMAND_HANDLER(handle_exit_command)
 static const struct command_registration telnet_command_handlers[] = {
        {
                .name = "exit",
-               .handler = &handle_exit_command,
+               .handler = handle_exit_command,
                .mode = COMMAND_EXEC,
                .help = "exit telnet session",
        },
        {
                .name = "telnet_port",
-               .handler = &handle_telnet_port_command,
+               .handler = handle_telnet_port_command,
                .mode = COMMAND_ANY,
-               .help = "port on which to listen "
-                       "for incoming telnet connections",
-               .usage = "<port>",
+               .help = "Specify port on which to listen "
+                       "for incoming telnet connections.  "
+                       "No arguments reports telnet port; zero disables.",
+               .usage = "[port_num]",
        },
        COMMAND_REGISTRATION_DONE
 };