[RFA/Ada(v2) 3/3] Document "info exceptions" and "-info-ada-exception" new commands.

[Joel Brobecker <brobecker at adacore dot com>]

Hello,

This is the doco & NEWS patch.

gdb/doc/ChangeLog:

        * gdb.texinfo (Ada): Add entry in menu for new "Ada Exceptions" node.
        (Ada Exceptions): New node.
        (GDB/MI): Add entry in menu for new "GDB/MI Ada Exceptions
        Commands" node.
        (GDB/MI Ada Exceptions Commands): New node.
        (GDB/MI Miscellaneous Commands): Document new "info-ada-exceptions"
        field in the output of the "-list-features" command.
        * NEWS: Add entry for the new "info exceptions" CLI command,
        and for the new "-info-ada-exceptions" GDB/MI command.

Tested by rebuilding and inspecting all doc formats.
OK to commit?

Thank you,
-- 
Joel

---
 gdb/NEWS            |  9 +++++
 gdb/doc/gdb.texinfo | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 103 insertions(+), 1 deletion(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index efeda68..62fc172 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -80,6 +80,12 @@ remove-symbol-file -a ADDRESS
   can be identified by its filename or by an address that lies within
   the boundaries of this symbol file in memory.
 
+info exceptions
+info exceptions REGEXP
+  Display the list of Ada exceptions defined in the program being
+  debugged.  If provided, only the exceptions whose name match REGEXP
+  are listed.
+
 * New options
 
 set debug symfile off|on
@@ -163,6 +169,9 @@ show startup-with-shell
   ** The new commands -catch-assert and -catch-exceptions insert
      catchpoints stopping the program when Ada exceptions are raised.
 
+  ** The new command -info-ada-exceptions provides the equivalent of
+     the new "info exceptions" command.
+
 * New system-wide configuration scripts
   A GDB installation now provides scripts suitable for use as system-wide
   configuration scripts for the following systems:
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 39498d7..3eed0af 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -14965,6 +14965,7 @@ to be difficult.
 * Omissions from Ada::          Restrictions on the Ada expression syntax.
 * Additions to Ada::            Extensions of the Ada expression syntax.
 * Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Exceptions::              Ada Exceptions
 * Ada Tasks::                   Listing and setting breakpoints in tasks.
 * Ada Tasks and Core Files::    Tasking Support when Debugging Core Files
 * Ravenscar Profile::           Tasking Support when using the Ravenscar
@@ -15289,6 +15290,42 @@ Manual, the elaboration code is invoked from a procedure called
 elaboration, simply use the following two commands:
 @code{tbreak adainit} and @code{run}.
 
+@node Ada Exceptions
+@subsubsection Ada Exceptions
+
+A command is provided to list all Ada exceptions:
+
+@table @code
+@kindex info exceptions
+@item info exceptions
+@itemx info exceptions @var{regexp}
+The @code{info exceptions} command allows you to list all Ada exceptions
+defined within the program being debugged, as well as their address.
+With a regular expression, @var{regexp}, as argument, only those exceptions
+whose name matches @var{regexp} are listed.
+@end table
+
+Below is a small example, showing how the command can be used, first
+without argument, and next with a regular expression passed as an
+argument.
+
+@smallexample
+(@value{GDBP}) info exceptions
+All defined Ada exceptions:
+constraint_error: 0x613da0
+program_error: 0x613d20
+storage_error: 0x613ce0
+tasking_error: 0x613ca0
+const.aint_global_e: 0x613b00
+(@value{GDBP}) info exceptions const.aint
+All Ada exceptions matching regular expression "const.aint":
+constraint_error: 0x613da0
+const.aint_global_e: 0x613b00
+@end smallexample
+
+It is also possible to ask @value{GDBN} to stop your program's execution
+when an exception is raised.  For more details, see @ref{Set Catchpoints}.
+
 @node Ada Tasks
 @subsubsection Extensions for Ada Tasks
 @cindex Ada, tasking
@@ -28603,6 +28640,7 @@ may repeat one or more times.
 @end ignore
 * GDB/MI Target Manipulation::
 * GDB/MI File Transfer Commands::
+* GDB/MI Ada Exceptions Commands::
 * GDB/MI Miscellaneous Commands::
 @end menu
 
@@ -34692,6 +34730,59 @@ The corresponding @value{GDBN} command is @samp{remote delete}.
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Ada Exceptions Commands
+@section Ada Exceptions @sc{gdb/mi} Commands
+
+@subheading The @code{-info-ada-exceptions} Command
+@findex -info-ada-exceptions
+
+@subsubheading Synopsis
+
+@smallexample
+ -info-ada-exceptions [ @var{regexp}]
+@end smallexample
+
+List all Ada exceptions defined within the program being debugged.
+With a regular expression @var{regexp}, only those exceptions whose
+name matches @var{regexp} are listed.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{info exceptions}.
+
+@subsubheading Result
+
+The result is a table of Ada exceptions.  The following columns are
+defined for each exception:
+
+@table @samp
+@item name
+The name of the exception.
+
+@item address
+The address of the exception.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-info-ada-exceptions aint
+^done,ada-exceptions=@{nr_rows="2",nr_cols="2",
+hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@},
+@{width="1",alignment="-1",col_name="address",colhdr="Address"@}],
+body=[@{name="constraint_error",address="0x0000000000613da0"@},
+@{name="const.aint_global_e",address="0x0000000000613b00"@}]@}
+@end smallexample
+
+@subheading Catching Ada Exceptions
+
+The commands describing how to ask @value{GDBN} to stop when a program
+raises an exception are described at @ref{Ada Exception GDB/MI
+Catchpoint Commands}.
+
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Miscellaneous Commands
 @section Miscellaneous @sc{gdb/mi} Commands
 
@@ -34877,7 +34968,9 @@ Indicates support for the @code{-data-read-memory-bytes} and the
 Indicates that changes to breakpoints and breakpoints created via the
 CLI will be announced via async records.
 @item ada-task-info
-Indicates support for the @code{-ada-task-info} command.
+indicates support for the @code{-ada-task-info} command.
+@item info-ada-exceptions
+indicates support for the @code{-info-ada-exceptions} command.
 @end table
 
 @subheading The @code{-list-target-features} Command
-- 
1.8.1.2