[binutils-gdb] DOCO: Enhance the menu to select function overloads with signatures

[Pierre-Marie de Rodat <pmderodat at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=3685b09fb85dc279762e19df310dc2f30e64b044

commit 3685b09fb85dc279762e19df310dc2f30e64b044
Author: Pierre-Marie de Rodat <derodat@adacore.com>
Date:   Thu Sep 3 17:34:58 2015 +0200

    DOCO: Enhance the menu to select function overloads with signatures
    
    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.

Diff:
---
 gdb/ChangeLog       |  5 +++++
 gdb/NEWS            |  8 ++++++++
 gdb/doc/ChangeLog   |  6 ++++++
 gdb/doc/gdb.texinfo | 56 ++++++++++++++++++++++++++++++++++++++++++++++-------
 4 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index f3537ea..b5d2431 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,8 @@
+2015-12-08  Pierre-Marie de Rodat  <derodat@adacore.com>
+
+	* NEWS: Announce this enhancement and the corresponding new
+	option.
+
 2015-12-07  Pierre-Marie de Rodat  <derodat@adacore.com>
 
 	* ada-lang.c (print_signatures): New.
diff --git a/gdb/NEWS b/gdb/NEWS
index a222dfb..280c8fe 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 enhanced 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/ChangeLog b/gdb/doc/ChangeLog
index 2c58ffe..6f05e36 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2015-12-08  Pierre-Marie de Rodat  <derodat@adacore.com>
+
+	* gdb.texinfo (Ada Mode Into): Move overloading support
+	description to its own node.
+	(Overloading support for Ada): New node.
+
 2015-11-30  Pedro Alves  <palves@redhat.com>
 
 	PR 14618
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b82f3c6..9f72c52 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,53 @@ object.
 
 @end itemize
 
+@node Overloading support for Ada
+@subsubsection Overloading support for Ada
+@cindex overloading, Ada
+
+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, @value{GDBN} 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 @kbd{0} and press @key{RET}) or to continue evaluation with a specific
+instance (type the corresponding number and press @key{RET}).
+
+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 @code{on} by default.
+@xref{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.
+@xref{Overloading support for Ada}.
+
+@end table
+
 @node Stopping Before Main Program
 @subsubsection Stopping at the Very Beginning