[PATCH] DOCO: Enhance the menu to select function overloads with signatures

[PATCH] DOCO: Enhance the menu to select function overloads with signatures

[Pierre-Marie de Rodat]

gdb/ChangeLog:

	* NEWS: Announce this enhancement and the corresponding new
	option.

gdb/doc/ChangeLog:

	* gdb.texinfo (Ada Mode Into): Move overloading support
	description to its own node.
	(Overloading support for Ada): New node.
---
 gdb/NEWS            |  8 ++++++++
 gdb/doc/gdb.texinfo | 57 ++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index a222dfb..060f1e2 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -28,6 +28,9 @@
   and "maint info program-spaces" now list the corresponding items in
   ascending ID order, for consistency with all other "info" commands.
 
+* In Ada, the overloads selection menu has been enhance to display the
+  parameter types and the return types for the matching overloaded subprograms.
+
 * New commands
 
 maint set target-non-stop (on|off|auto)
@@ -52,6 +55,11 @@ set remote thread-events
 show remote thread-events
   Set/show the use of thread create/exit events.
 
+set ada print-signatures on|off
+show ada print-signatures"
+  Control whether parameter types and return types are displayed in overloads
+  selection menus. It is activaled (@code{on}) by default.
+
 * The "disassemble" command accepts a new modifier: /s.
   It prints mixed source+disassembly like /m with two differences:
   - disassembled instructions are now printed in program order, and
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b82f3c6..db78ebd0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -15606,6 +15606,8 @@ to be difficult.
                                    in @value{GDBN}.
 * Omissions from Ada::          Restrictions on the Ada expression syntax.
 * Additions to Ada::            Extensions of the Ada expression syntax.
+* Overloading support for Ada:: Support for expressions involving overloaded
+                                   subprograms.
 * Stopping Before Main Program:: Debugging the program during elaboration.
 * Ada Exceptions::              Ada Exceptions
 * Ada Tasks::                   Listing and setting breakpoints in tasks.
@@ -15653,13 +15655,6 @@ mostly for documenting command files.  The standard @value{GDBN} comment
 (@samp{#}) still works at the beginning of a line in Ada mode, but not in the 
 middle (to allow based literals).
 
-The debugger supports limited overloading.  Given a subprogram call in which
-the function symbol has multiple definitions, it will use the number of 
-actual parameters and some information about their types to attempt to narrow
-the set of definitions.  It also makes very limited use of context, preferring
-procedures to functions in the context of the @code{call} command, and
-functions to procedures elsewhere. 
-
 @node Omissions from Ada
 @subsubsection Omissions from Ada
 @cindex Ada, omissions from
@@ -15920,6 +15915,54 @@ object.
 
 @end itemize
 
+@node Overloading support for Ada
+@subsubsection Overloading support for Ada
+@cindex Ada, overloading
+
+The debugger supports limited overloading.  Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of
+actual parameters and some information about their types to attempt to narrow
+the set of definitions.  It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere.
+
+If, after narrowing, the set of matching definitions still contains more than
+one definition, GDB will display a menu to query which one it should use, for
+instance:
+
+@smallexample
+(@value{GDBP}) print f(1)
+Multiple matches for f
+[0] cancel
+[1] foo.f (integer) return boolean at foo.adb:23
+[2] foo.f (foo.new_integer) return boolean at foo.adb.28
+> 
+@end smallexample
+
+In this case, just select one menu entry either to cancel expression evaluation
+(type @code{0} and press @code{ENTER}) or to continue evaluation with a
+specific overloaded entity (type the corresponding number and press
+@code{ENTER}).
+
+Here are a couple of commands to customize @value{GDBN}'s behavior in this
+case:
+
+@table @code
+
+@kindex set ada print-signatures
+@item set ada print-signatures
+Control whether parameter types and return types are displayed in overloads
+selection menus. It is activaled (@code{on}) by default.
+@pxref{Overloading support for Ada}
+
+@kindex show ada print-signatures
+@item show ada print-signatures
+Show the current setting for displaying parameter types and return types in
+overloads selection menu.
+@pxref{Overloading support for Ada}
+
+@end table
+
 @node Stopping Before Main Program
 @subsubsection Stopping at the Very Beginning
 
-- 
2.6.2

Re: [PATCH] DOCO: Enhance the menu to select function overloads with signatures

[Eli Zaretskii]

> From: Pierre-Marie de Rodat <derodat@adacore.com>
> Cc: Joel Brobecker <brobecker@adacore.com>,	Pierre-Marie de Rodat <derodat@adacore.com>
> Date: Mon,  7 Dec 2015 13:35:48 +0100
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index a222dfb..060f1e2 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -28,6 +28,9 @@
>    and "maint info program-spaces" now list the corresponding items in
>    ascending ID order, for consistency with all other "info" commands.
>  
> +* In Ada, the overloads selection menu has been enhance to display the
                                                   ^^^^^^^
"enhanced"

> +show ada print-signatures"
> +  Control whether parameter types and return types are displayed in overloads
> +  selection menus. It is activaled (@code{on}) by default.
                    ^^
Two spaces between sentences, please.

> +@node Overloading support for Ada
> +@subsubsection Overloading support for Ada
> +@cindex Ada, overloading

This index entry is backwards: it should be "overloading, Ada".
That's because the reader is much more likely to think of
"overloading" than of "Ada" when she wants to look up this entry.

> +If, after narrowing, the set of matching definitions still contains more than
> +one definition, GDB will display a menu to query which one it should use, for
                   ^^^
"@value{GDBN}"

> +In this case, just select one menu entry either to cancel expression evaluation
> +(type @code{0} and press @code{ENTER}) or to continue evaluation with a
         ^^^^^^^^           ^^^^^^^^^^^^
@kbd{0} and @key{RET}, respectively.  These are GNU conventions for
markup of user input and key names.

> +specific overloaded entity (type the corresponding number and press

Won't "specific instance" be more accurate?  Those entries are no
longer overloaded, are they?

> +@code{ENTER}).

@key{RET}.

> +@kindex set ada print-signatures
> +@item set ada print-signatures
> +Control whether parameter types and return types are displayed in overloads
> +selection menus. It is activaled (@code{on}) by default.
                  ^^
Two spaces where indicated.  Also, I thing you can safely delete
"activated" and leave just @code{on} without parentheses.

> +@pxref{Overloading support for Ada}

@xref, not @pxref, and place a period after the closing brace.

OK with these fixed.

Thanks.

Re: [PATCH] DOCO: Enhance the menu to select function overloads with signatures

[Pierre-Marie de Rodat]

On 12/07/2015 05:00 PM, Eli Zaretskii wrote:
>> +* In Ada, the overloads selection menu has been enhance to display the
>                                                     ^^^^^^^
> "enhanced"

Fixed.

>> +show ada print-signatures"
>> +  Control whether parameter types and return types are displayed in overloads
>> +  selection menus. It is activaled (@code{on}) by default.
>                      ^^
> Two spaces between sentences, please.

Fixed here and in the other occurence.

> This index entry is backwards: it should be "overloading, Ada".
> That's because the reader is much more likely to think of
> "overloading" than of "Ada" when she wants to look up this entry.

Fixed, thank you for the rationale.

>> +If, after narrowing, the set of matching definitions still contains more than
>> +one definition, GDB will display a menu to query which one it should use, for
>                     ^^^
> "@value{GDBN}"

Fixed.

> @kbd{0} and @key{RET}, respectively.  These are GNU conventions for
> markup of user input and key names.

Done, thanks.

>> +specific overloaded entity (type the corresponding number and press
>
> Won't "specific instance" be more accurate?  Those entries are no
> longer overloaded, are they?

I’m not sure what you mean here: the reason we have this menu is because 
the name “f” is overloaded (i.e. multiple entities have the same name). 
They still have the same name when the user is about to select one of 
them, so they are still overloaded.

… Anyway I switched to “specific instance” as it’s correct. ;-)

>> +@code{ENTER}).
>
> @key{RET}.

Fixed.

>> +@kindex set ada print-signatures
>> +@item set ada print-signatures
>> +Control whether parameter types and return types are displayed in overloads
>> +selection menus. It is activaled (@code{on}) by default.
>                    ^^
> Two spaces where indicated.  Also, I thing you can safely delete
> "activated" and leave just @code{on} without parentheses.

Done.

>> +@pxref{Overloading support for Ada}
>
> @xref, not @pxref, and place a period after the closing brace.

Fixed the two occurences.

> OK with these fixed.
>
> Thanks.

Pushed now. Many thanks for reviewing!

-- 
Pierre-Marie de Rodat