[PATCH] Improve clear command's documentation

Pedro Alves
2022-05-31T11:06:11Z

Handling this one issue at a time.

On 2022-05-30 17:15, Eli Zaretskii wrote:
>> Date: Mon, 30 May 2022 15:44:59 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>>> -@item clear @var{location}
>>>> -Delete any breakpoints set at the specified @var{location}.
>>>> -@xref{Specify Location}, for the various forms of @var{location}; the
>>>> -most useful ones are listed below:
>>>> +@item clear @var{locspec}
>>>> +Delete breakpoints with code locations that match @var{locspec}.
>>> ^^^^^^^^^^^^^^^^^^^^^^^^
>>> "that are the result of resolving @var{locspec}"
>>
>> That wouldn't actually be correct for this command. For example:
>>
>> (top-gdb) b gdb.c:29
>> Breakpoint 4 at 0x555555641091: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29.
>> (top-gdb) b *0x555555641092
>> Breakpoint 5 at 0x555555641092: file /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c, line 29.
>> (top-gdb) info breakpoints
>> Num Type Disp Enb Address What
>> 4 breakpoint keep y 0x0000555555641091 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29
>> 5 breakpoint keep y 0x0000555555641092 in main(int, char**) at /home/pedro/gdb/binutils-gdb/src/gdb/gdb.c:29
>>
>> "gdb.c:29" resolves to address 0x0000555555641091, as can be seen when breakpoint 4 was
>> created. However, this:
>>
>> (top-gdb) clear gdb.c:29
>> Deleted breakpoints 4 5
>>
>> ... also deletes breakpoint 5. GDB deleted it because its code location also matches
>> the user input.
>
> But then "matches locspec" is also inaccurate, and for the same
> reason: they are two equivalent ways of describing the same process of
> arriving at a code location from a location spec, or at least that's
> how the text used them until now.
>
>> This is explained just a bit below, here:
>>
>> @item clear @var{linenum}
>> @itemx clear @var{filename}:@var{linenum}
>> Delete any breakpoints set at or within the code of the specified
>> @var{linenum} of the specified @var{filename}.
>> @end table
>>
>> Key here are "or within the code", and talking about the _specified_
>> linenum/filename, not the resolved line/filename.
>
> Then we need some change of text to the same effect where "clear
> LOCSPEC" is described, right?

How about this, basically a complete rewrite of the clear command's
documentation:

From 2efda4c0040ba088da5e0e03b5afdd2b0248ec5b Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Tue, 31 May 2022 10:54:17 +0100
Subject: [PATCH] Improve clear command's documentation

Change-Id: I9440052fd28f795d6f7c93a4576beadd21f28885
---
gdb/doc/gdb.texinfo | 46 +++++++++++++++++++++++++++++++++++----------
1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3cf4e2c73c0..b497901473d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5443,21 +5443,47 @@ the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.

@item clear @var{locspec}
-Delete breakpoints with code locations that match @var{locspec}.
-@xref{Location Specifications}, for the various forms of
-@var{locspec}; the most useful ones are listed below:
+Delete breakpoints with code locations that match either address,
+source file and line number, or function name specified in
+@var{locspec}. @xref{Location Specifications}, for the various forms
+of @var{locspec}.
+
+The location spec to breakpoint code location matching is done in the
+following ways, depending on what the location spec specifies:

@table @code
-@item clear @var{function}
-@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the named @var{function}.
+@item if @var{locspec} specifies a line number
+If @var{locspec} specifies a line number, such as e.g., with one of
+the following forms:

-@item clear @var{linenum}
-@itemx clear @var{filename}:@var{linenum}
-Delete any breakpoints set at or within the code of the specified
-@var{linenum} of the specified @var{filename}.
+@table @code
+@item @code{clear @var{linenum}}
+@item @code{clear @var{filename}:@var{linenum}}
+@item @code{clear -line @var{linenum}}
+@item @code{clear -source @var{filename} -line @var{linenum}}
@end table

+@noindent
+then the command deletes any breakpoints with a code location set at
+or within the code of the specified @var{linenum} of files that match
+the specified @var{filename}, or of files that match the current
+source file, if no file name was specified.
+
+@item if @var{locspec} specifies an address
+If @var{locspec} specifies an address, with @code{clear *@var{addr}},
+then the command deletes any breakpoints with a code location set at
+the given address.
+
+@item if @var{locspec} specifies a function
+If @var{locspec} specifies a function, such as with @code{clear
+@var{function}} or @code{clear -function @var{function}}, then the
+command deletes any breakpoints with a code location set at entry to a
+function whose name matches @var{function}.
+@end table
+
+Ambiguity in file name and function name matching can be resolved as
+described in @ref{Location Specifications}.
+
@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}

base-commit: 5541bfdc97936581c0ead915e9117e22f21bdb12
--
2.36.0