Re: [PATCH] Enhance break command help

[Andrew STUBBS <andrew.stubbs@st.com>]

[-- Attachment #1: Type: text/plain, Size: 1016 bytes --]

Eli Zaretskii wrote:
> Okay for the breakpoint.c patch, thanks.  I have only one comment:
> please remove all the "The" articles before argument names, like this:
> 
>   +LOCATION may be a line number, function name, or \"*\" and an address.\n\
> 
> instead of
> 
>   +The LOCATION may be a line number, function name, or \"*\" and an address.\n\
> 
> Also, can I ask you for a small favor?  There are other *break and
> similar commands defined in breakpoint.c, whose doc strings reference
> those of other commands and eventually the one you fixed.  I never
> liked those references: the user shouldn't need to look up several
> commands she doesn't care about to arrive at the required info.  So
> could you please modify all those other doc strings to simply repeat
> the arguments' description you just fixed?

How about the attached? I have broken out the common parts into a macro 
to prevent duplication and hopefully make future maintenance easier.

I have tested gdb.base/help.exp and all is well.

Andrew

[-- Attachment #2: break-help.patch --]
[-- Type: text/plain, Size: 15291 bytes --]

2005-12-02  Andrew Stubbs  <andrew.stubbs@st.com>

	* breakpoint.c (BREAK_ARGS_HELP): New mecro.
	(_initialize_breakpoint): Enhance break, tbreak, hbreak and thbreak
	commands' help by adding more information and using BREAK_ARGS_HELP
	to duplicate the common parts.  Remove now-redundant cross-references.

testsuite/
	* gdb.base/help.exp (help b, help br, help bre, help brea)
	(help break): Update the expected message.

Index: src/gdb/breakpoint.c
===================================================================
--- src.orig/gdb/breakpoint.c	2005-12-02 12:24:19.000000000 +0000
+++ src/gdb/breakpoint.c	2005-12-02 12:47:08.000000000 +0000
@@ -7653,6 +7653,25 @@ decode_line_spec_1 (char *string, int fu
   return sals;
 }
 \f
+/* This help string is used for the break, hbreak, tbreak and thbreak commands.
+   It is defined as a macro to prevent duplication.
+   COMMAND should be a string constant containing the name of the command.  */
+#define BREAK_ARGS_HELP(command) \
+command" [LOCATION] [thread THREADNUM] [if CONDITION]\n\
+LOCATION may be a line number, function name, or \"*\" and an address.\n\
+If a line number is specified, break at start of code for that line.\n\
+If a function is specified, break at start of code for that function.\n\
+If an address is specified, break at that exact address.\n\
+With no LOCATION, uses current execution address of selected stack frame.\n\
+This is useful for breaking on return to a stack frame.\n\
+\n\
+THREADNUM is the number from \"info threads\".\n\
+CONDITION is a boolean expression.\n\
+\n\
+Multiple breakpoints at one place are permitted, and useful if conditional.\n\
+\n\
+Do \"help breakpoints\" for info on other commands dealing with breakpoints."
+
 void
 _initialize_breakpoint (void)
 {
@@ -7688,22 +7707,28 @@ Usage is `condition N COND', where N is 
 expression to be evaluated whenever breakpoint N is reached."));
 
   c = add_com ("tbreak", class_breakpoint, tbreak_command, _("\
-Set a temporary breakpoint.  Args like \"break\" command.\n\
+Set a temporary breakpoint.\n\
 Like \"break\" except the breakpoint is only temporary,\n\
 so it will be deleted when hit.  Equivalent to \"break\" followed\n\
-by using \"enable delete\" on the breakpoint number."));
+by using \"enable delete\" on the breakpoint number.\n\
+\n"
+BREAK_ARGS_HELP ("tbreak")));
   set_cmd_completer (c, location_completer);
 
   c = add_com ("hbreak", class_breakpoint, hbreak_command, _("\
-Set a hardware assisted  breakpoint. Args like \"break\" command.\n\
+Set a hardware assisted  breakpoint.\n\
 Like \"break\" except the breakpoint requires hardware support,\n\
-some target hardware may not have this support."));
+some target hardware may not have this support.\n\
+\n"
+BREAK_ARGS_HELP ("hbreak")));
   set_cmd_completer (c, location_completer);
 
   c = add_com ("thbreak", class_breakpoint, thbreak_command, _("\
-Set a temporary hardware assisted breakpoint. Args like \"break\" command.\n\
+Set a temporary hardware assisted breakpoint.\n\
 Like \"hbreak\" except the breakpoint is only temporary,\n\
-so it will be deleted when hit."));
+so it will be deleted when hit.\n\
+\n"
+BREAK_ARGS_HELP ("thbreak")));
   set_cmd_completer (c, location_completer);
 
   add_prefix_cmd ("enable", class_breakpoint, enable_command, _("\
@@ -7808,17 +7833,8 @@ is executing in.\n\
 See also the \"delete\" command which clears breakpoints by number."));
 
   c = add_com ("break", class_breakpoint, break_command, _("\
-Set breakpoint at specified line or function.\n\
-Argument may be line number, function name, or \"*\" and an address.\n\
-If line number is specified, break at start of code for that line.\n\
-If function is specified, break at start of code for that function.\n\
-If an address is specified, break at that exact address.\n\
-With no arg, uses current execution address of selected stack frame.\n\
-This is useful for breaking on return to a stack frame.\n\
-\n\
-Multiple breakpoints at one place are permitted, and useful if conditional.\n\
-\n\
-Do \"help breakpoints\" for info on other commands dealing with breakpoints."));
+Set breakpoint at specified line or function.\n"
+BREAK_ARGS_HELP ("break")));
   set_cmd_completer (c, location_completer);
 
   add_com_alias ("b", "break", class_run, 1);
Index: src/gdb/testsuite/gdb.base/help.exp
===================================================================
--- src.orig/gdb/testsuite/gdb.base/help.exp	2005-12-02 12:24:18.000000000 +0000
+++ src/gdb/testsuite/gdb.base/help.exp	2005-12-02 12:55:50.000000000 +0000
@@ -50,15 +50,15 @@ gdb_test "help append binary value" "App
 # test help attach
 gdb_test "help attach" "Attach to a process or file outside of GDB\.\[\r\n\]+This command attaches to another target, of the same type as your last\[\r\n\]+\"target\" command \\(\"info files\" will show your target stack\\)\.\[\r\n\]+The command may take as argument a process id or a device file\.\[\r\n\]+For a process id, you must have permission to send the process a signal,\[\r\n\]+and it must have the same effective uid as the debugger\.\[\r\n\]+When using \"attach\" with a process id, the debugger finds the\[\r\n\]+program running in the process, looking first in the current working\[\r\n\]+directory, or \\(if not found there\\) using the source file search path\[\r\n\]+\\(see the \"directory\" command\\)\.  You can also use the \"file\" command\[\r\n\]+to specify the program, and to load its symbol table\." "help attach"
 # test help breakpoint "b" abbreviation
-gdb_test "help b" "Set breakpoint at specified line or function\.\[\r\n\]+Argument may be line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If line number is specified, break at start of code for that line\.\[\r\n\]+If function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no arg, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"b\" abbreviation"
+gdb_test "help b" "Set breakpoint at specified line or function\.\[\r\n\]+break \\\[LOCATION\] \\\[thread THREADNUM\] \\\[if CONDITION\]\[\r\n\]+LOCATION may be a line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If a line number is specified, break at start of code for that line\.\[\r\n\]+If a function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no LOCATION, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+THREADNUM is the number from \"info threads\"\.\[\r\n\]+CONDITION is a boolean expression\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"b\" abbreviation"
 # test help breakpoint "br" abbreviation
-gdb_test "help br" "Set breakpoint at specified line or function\.\[\r\n\]+Argument may be line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If line number is specified, break at start of code for that line\.\[\r\n\]+If function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no arg, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"br\" abbreviation"
+gdb_test "help br" "Set breakpoint at specified line or function\.\[\r\n\]+break \\\[LOCATION\] \\\[thread THREADNUM\] \\\[if CONDITION\]\[\r\n\]+LOCATION may be a line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If a line number is specified, break at start of code for that line\.\[\r\n\]+If a function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no LOCATION, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+THREADNUM is the number from \"info threads\"\.\[\r\n\]+CONDITION is a boolean expression\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"br\" abbreviation"
 # test help breakpoint "bre" abbreviation
-gdb_test "help bre" "Set breakpoint at specified line or function\.\[\r\n\]+Argument may be line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If line number is specified, break at start of code for that line\.\[\r\n\]+If function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no arg, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"bre\" abbreviation"
+gdb_test "help bre" "Set breakpoint at specified line or function\.\[\r\n\]+break \\\[LOCATION\] \\\[thread THREADNUM\] \\\[if CONDITION\]\[\r\n\]+LOCATION may be a line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If a line number is specified, break at start of code for that line\.\[\r\n\]+If a function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no LOCATION, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+THREADNUM is the number from \"info threads\"\.\[\r\n\]+CONDITION is a boolean expression\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"bre\" abbreviation"
 # test help breakpoint "brea" abbreviation
-gdb_test "help brea" "Set breakpoint at specified line or function\.\[\r\n\]+Argument may be line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If line number is specified, break at start of code for that line\.\[\r\n\]+If function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no arg, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"brea\" abbreviation"
+gdb_test "help brea" "Set breakpoint at specified line or function\.\[\r\n\]+break \\\[LOCATION\] \\\[thread THREADNUM\] \\\[if CONDITION\]\[\r\n\]+LOCATION may be a line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If a line number is specified, break at start of code for that line\.\[\r\n\]+If a function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no LOCATION, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+THREADNUM is the number from \"info threads\"\.\[\r\n\]+CONDITION is a boolean expression\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"brea\" abbreviation"
 # test help breakpoint "break" abbreviation
-gdb_test "help break" "Set breakpoint at specified line or function\.\[\r\n\]+Argument may be line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If line number is specified, break at start of code for that line\.\[\r\n\]+If function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no arg, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"break\" abbreviation"
+gdb_test "help break" "Set breakpoint at specified line or function\.\[\r\n\]+break \\\[LOCATION\] \\\[thread THREADNUM\] \\\[if CONDITION\]\[\r\n\]+LOCATION may be a line number, function name, or \"\[*\]\" and an address\.\[\r\n\]+If a line number is specified, break at start of code for that line\.\[\r\n\]+If a function is specified, break at start of code for that function\.\[\r\n\]+If an address is specified, break at that exact address\.\[\r\n\]+With no LOCATION, uses current execution address of selected stack frame\.\[\r\n\]+This is useful for breaking on return to a stack frame\.\[\r\n\]+THREADNUM is the number from \"info threads\"\.\[\r\n\]+CONDITION is a boolean expression\.\[\r\n\]+Multiple breakpoints at one place are permitted, and useful if conditional\.\[\r\n\]+Do \"help breakpoints\" for info on other commands dealing with breakpoints\." "help breakpoint \"break\" abbreviation"
 # test help breakpoints
 gdb_test "help breakpoints" "Making program stop at certain points\.\[\r\n\]+List of commands:\[\r\n\]+awatch -- Set a watchpoint for an expression\[\r\n\]+break -- Set breakpoint at specified line or function\[\r\n\]+catch -- Set catchpoints to catch events\[\r\n\]+clear -- Clear breakpoint at specified line or function\[\r\n\]+commands -- Set commands to be executed when a breakpoint is hit\[\r\n\]+condition -- Specify breakpoint number N to break only if COND is true\[\r\n\]+delete -- Delete some breakpoints or auto-display expressions\[\r\n\]+disable -- Disable some breakpoints\[\r\n\]+enable -- Enable some breakpoints\[\r\n\]+hbreak -- Set a hardware assisted  breakpoint\[\r\n\]+ignore -- Set ignore-count of breakpoint number N to COUNT\[\r\n\]+rbreak -- Set a breakpoint for all functions matching REGEXP\[\r\n\]+rwatch -- Set a read watchpoint for an expression\[\r\n\]+tbreak -- Set a temporary breakpoint\[\r\n\]+tcatch -- Set temporary catchpoints to catch events\[\r\n\]+thbreak -- Set a temporary hardware assisted breakpoint\[\r\n\]+watch -- Set a watchpoint for an expression\[\r\n\]+Type \"help\" followed by command name for full documentation\.\[\r\n\]+Command name abbreviations are allowed if unambiguous\." "help breakpoints"
 # test help backtrace "bt" abbreviation