[PATCH 40/40] Document breakpoints / linespec & co improvements (manual + NEWS)

[Pedro Alves]

On 06/02/2017 02:01 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Fri,  2 Jun 2017 13:22:38 +0100
>>
>> +For example, assuming a program with symbols named @code{A::B::func}
>> +and @code{B::func}, both commands @code{break -function func} and
>> +@code{break -function B::func} set a breakpoint on both symbols.
> 
> The 2 commands are long and include whitespace, so I'd suggest
> enclosing each one in @w{..}, to avoid a line break in the middle of a
> command.
> 
> Also, I think @kbd is more appropriate here than @code, since you mean
> commands the user will type, not just command names.
> 
> I'm surprised you didn't change anything where the manual discusses
> quoting of names and symbols.  For example, the node "Completion"
> explicitly describes a use case with overloaded functions in C++; the
> node "Symbols" describes a case with "::" that requires quoting.
> There's another example in "Machine Code", and also in "Ambiguous
> Expression", and in "Variables".  Maybe you already reviewed all of
> those and concluded no changes were necessary, but I just thought I'd
> mention them.

Thanks, I just didn't think of looking for quoting bits in the
manual, for some reason.  I'll take a closer look.

> 
>> +  ** GDB now has a much improved linespec and explicit locations TAB
>> +     completion support, that better understands what you're
>> +     completing and offers better suggestions.
> 
> Is this a general improvement, or is it limited to C++ symbols?  If
> the latter, suggest to mention that.

You're right.  It's more general than C++.

> 
>> +  ** GDB can now complete function parameters in linespecs and
>> +     explicit locations, even without quoting.  When setting
>> +     breakpoints, quoting around functions names to help with
>> +     TAB-completion is generally no longer necessary.
> 
> Likewise.
> 
>> +  ** GDB can now set breakpoints functions marked with [abi:cxx11]
>> +     tags.
> 
> "on functions", I think.
> 
> And btw, what are those tags?  

This is the best document that I know describing them:

 https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/

Functions that ended up requiring an abi tag are demangled like this:

  string_printf[abi:cxx11](char const*, ...)
               ^^^^^^^^^^^

That's an actual function in GDB.  It ended requiring an ABI tag
because it returns std::string.  See intro of patch 39 for more.

> I don't think I see them documented in the manual; did I miss something?

Hmm, I guess we could add something, indeed.

Thanks,
Pedro Alves