[PATCH] Improve clear command's documentation

[Pedro Alves <pedro@palves.net>]

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