[RFA/doco] expand a bit the in-GDB help for the "catch exception" help text

[RFA/doco] expand a bit the in-GDB help for the "catch exception" help text

[Joel Brobecker]

Hello,

One of our users remarked that the help doesn't mention the fact that
the "catch exception" supports the special argument "unhandled" to catch
exceptions which do not have a handler. This patch changes the output
of...

 | (gdb) help catch exception
 | Catch Ada exceptions, when raised.
 | With an argument, catch only exceptions with the given name.

... to ...

 | (gdb) help catch exception
 | Catch Ada exceptions, when raised.
 | Usage: catch exception [ ARG ]
 |
 | Without any argument, stop when any Ada exception is raised.
 | If ARG is "unhandled" (without the quotes), stop when an unhandledis raised.
 | Otherwise, the catchpoint only stops when the name of the exception being
 | raised is the same as ARG.

gdb/ChangeLog:

        * ada-lang.c (_initialize_ada_language): Expand the help text
        for the "catch exception" command.

Tested on x86_64-linux, no regression.

OK to push? Or any suggestions?

Thank you,
-- 
Joel

---
 gdb/ada-lang.c | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/gdb/ada-lang.c b/gdb/ada-lang.c
index f552f13..dbd258a 100644
--- a/gdb/ada-lang.c
+++ b/gdb/ada-lang.c
@@ -14508,7 +14508,14 @@ overloads selection menu is activated"),
 
   add_catch_command ("exception", _("\
 Catch Ada exceptions, when raised.\n\
-With an argument, catch only exceptions with the given name."),
+Usage: catch exception [ ARG ]\n\
+\n\
+Without any argument, stop when any Ada exception is raised.\n\
+If ARG is \"unhandled\" (without the quotes), only stop when the exception\n\
+being raised does not have a handler (and will therefore lead to the task's\n\
+termination).\n\
+Otherwise, the catchpoint only stops when the name of the exception being\n\
+raised is the same as ARG."),
 		     catch_ada_exception_command,
                      NULL,
 		     CATCH_PERMANENT,
-- 
2.1.4

Re: [RFA/doco] expand a bit the in-GDB help for the "catch exception" help text

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Fri, 11 Jan 2019 09:22:51 -0500
> 
>  | (gdb) help catch exception
>  | Catch Ada exceptions, when raised.
>  | Usage: catch exception [ ARG ]
>  |
>  | Without any argument, stop when any Ada exception is raised.
>  | If ARG is "unhandled" (without the quotes), stop when an unhandledis raised.
>  | Otherwise, the catchpoint only stops when the name of the exception being
>  | raised is the same as ARG.
> 
> gdb/ChangeLog:
> 
>         * ada-lang.c (_initialize_ada_language): Expand the help text
>         for the "catch exception" command.
> 
> Tested on x86_64-linux, no regression.
> 
> OK to push? Or any suggestions?

The text you propose LGTM, thanks (the text above includes a typo, but
the source patch gets it right).

pushed: [RFA/doco] expand a bit the in-GDB help for the "catch exception" help text

[Joel Brobecker]

> > gdb/ChangeLog:
> > 
> >         * ada-lang.c (_initialize_ada_language): Expand the help text
> >         for the "catch exception" command.
> > 
> > Tested on x86_64-linux, no regression.
> > 
> > OK to push? Or any suggestions?
> 
> The text you propose LGTM, thanks (the text above includes a typo, but
> the source patch gets it right).

Indeed; I accidently copy/pasted an old version of the text into
the commit log! The version I pushed has the correct text.

Thank you Eli!
-- 
Joel