Re: [PATCH 3/3] [Ada/doco] Document the new -ada-task-info GDB/MI command.

[Joel Brobecker <brobecker at adacore dot com>]

> > +@item state
> > +The current state of the task.
> 
> Would it be a good idea to enumerate the possible states here?  Or is
> that common knowledge for anyone who is an Ada programmer?

It's a bit of both. But the list of states is already provided
inside the documentation of the `info tasks' command, so I added
a couple of references to that section of the manual:
  - One next to the part where I mention the `info tasks' command;
  - One inside the description of the `state' field, mentioning
    explicitly that the list of possible states is described there.

> > +@smallexample
> > +-thread-info
> > +^done,tasks=@{nr_rows="3",nr_cols="8",
> 
> You are documenting -ada-task-info, so why the example is for a
> different command?

That's a good catch - copy/paste typo. The output is correct, though.

> > +@item ada-task-info
> > +Indicates the presence of the @code{-ada-task-info} command.
> 
> I would use "availability of" or "support for", rather than "presence
> of".  (Yes, I know the other items use the same language you did; I
> think they all should be changed.)

OK. Fixed as suggested.  I also went ahead and modified the others
(that's the second patch, which can be applied independently of
the first).

[Ada/doco] Document the new -ada-task-info GDB/MI command.
gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Ada Tasking Commands): New node.
        (GDB/MI Miscellaneous Commands): Add `ada-task-info'
        as possible feature returned by the `-list-features'
        command.

[doco] rephrase `presence of' with `support for'.
gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Miscellaneous Commands): Minor
        rephasing.

-- 
Joel

commit 306d6a4adb5d2351b8c602a5e64d5a9ea6ca36d1
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Fri Sep 16 11:28:43 2011 -0700

    [Ada/doco] Document the new -ada-task-info GDB/MI command.
    
    gdb/doc/ChangeLog:
    
            * gdb.texinfo (GDB/MI Ada Tasking Commands): New node.
            (GDB/MI Miscellaneous Commands): Add `ada-task-info'
            as possible feature returned by the `-list-features'
            command.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 051377d..440aac3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24765,6 +24765,7 @@ may repeat one or more times.
 * GDB/MI Breakpoint Commands::
 * GDB/MI Program Context::
 * GDB/MI Thread Commands::
+* GDB/MI Ada Tasking Commands::
 * GDB/MI Program Execution::
 * GDB/MI Stack Manipulation::
 * GDB/MI Variable Objects::
@@ -26641,6 +26642,83 @@ args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
 @end smallexample
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Ada Tasking Commands
+@section @sc{gdb/mi} Ada Tasking Commands
+
+@subheading The @code{-ada-task-info} Command
+@findex -ada-task-info
+
+@subsubheading Synopsis
+
+@smallexample
+ -ada-task-info [ @var{task-id} ]
+@end smallexample
+
+Reports information about either a specific Ada task, if the
+@var{task-id} parameter is present, or about all Ada tasks.
+
+@subsubheading @value{GDBN} Command
+
+The @samp{info tasks} command prints the same information
+about all Ada tasks (@pxref{Ada Tasks}).
+
+@subsubheading Result
+
+The result is a table of Ada tasks.  The following columns are
+defined for each Ada task:
+
+@table @samp
+@item current
+This field exists only for the current thread.  It has the value @samp{*}.
+
+@item id
+The identifier that @value{GDBN} uses to refer to the Ada task.
+
+@item task-id
+The identifier that the target uses to refer to the Ada task.
+
+@item thread-id
+The identifier of the thread corresponding to the Ada task.
+
+This field should always exist, as Ada tasks are always implemented
+on top of a thread.  But if @value{GDBN} cannot find this corresponding
+thread for any reason, the field is omitted.
+
+@item parent-id
+This field exists only when the task was created by another task.
+In this case, it provides the ID of the parent task.
+
+@item priority
+The base priority of the task.
+
+@item state
+The current state of the task.  For a detailed description of the
+possible states, see @ref{Ada Tasks}.
+
+@item name
+The name of the task.
+
+@end table
+
+@subsubheading Example
+
+@smallexample
+-ada-task-info
+^done,tasks=@{nr_rows="3",nr_cols="8",
+hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@},
+@{width="3",alignment="1",col_name="id",colhdr="ID"@},
+@{width="9",alignment="1",col_name="task-id",colhdr="TID"@},
+@{width="4",alignment="1",col_name="thread-id",colhdr=""@},
+@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@},
+@{width="3",alignment="1",col_name="priority",colhdr="Pri"@},
+@{width="22",alignment="-1",col_name="state",colhdr="State"@},
+@{width="1",alignment="2",col_name="name",colhdr="Name"@}],
+body=[@{current="*",id="1",task-id="   644010",thread-id="1",priority="48",
+state="Child Termination Wait",name="main_task"@}]@}
+(gdb)
+@end smallexample
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Program Execution
 @section @sc{gdb/mi} Program Execution
 
@@ -30300,7 +30378,8 @@ Indicates presense of the @code{-data-read-memory-bytes} and the
 @item breakpoint-notifications
 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.
 @end table
 
 @subheading The @code{-list-target-features} Command

commit 2971ef39a4328682ba06195ea12918bacfe54733
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Mon Sep 19 11:23:42 2011 -0700

    [doco] rephrase `presence of' with `support for'.
    
            * gdb.texinfo (GDB/MI Miscellaneous Commands): Minor
            rephasing.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 440aac3..3ace5c4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -30361,19 +30361,20 @@ The current list of features is:
 
 @table @samp
 @item frozen-varobjs
-Indicates presence of the @code{-var-set-frozen} command, as well 
-as possible presense of the @code{frozen} field in the output 
+Indicates support for the @code{-var-set-frozen} command, as well
+as possible presense of the @code{frozen} field in the output
 of @code{-varobj-create}.
 @item pending-breakpoints
-Indicates presence of the @option{-f} option to the @code{-break-insert} command.
+Indicates support for the @option{-f} option to the @code{-break-insert}
+command.
 @item python
-Indicates presence of Python scripting support, Python-based
+Indicates Python scripting support, Python-based
 pretty-printing commands, and possible presence of the
 @samp{display_hint} field in the output of @code{-var-list-children}
 @item thread-info
-Indicates presence of the @code{-thread-info} command.
+Indicates support for the @code{-thread-info} command.
 @item data-read-memory-bytes
-Indicates presense of the @code{-data-read-memory-bytes} and the
+Indicates support for the @code{-data-read-memory-bytes} and the
 @code{-data-write-memory-bytes} commands.
 @item breakpoint-notifications
 Indicates that changes to breakpoints and breakpoints created via the