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

[Pierre-Marie de Rodat <derodat@adacore.com>]

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