doc: Improve documentation about MI thread output

I noticed that the documentation on how the info about threads is output
in MI is duplicated and not up to date.  The duplication is between the
"GDB/MI Thread Information" page and the -thread-info result
description.

I improved the "GDB/MI Thread Information" page a bit and referred to it
in the -thread-info doc.  This way, the -thread-info doc is more precise
(it did not mention the "threads" and "current-thread-id" attributes)
and concise.

gdb/doc/ChangeLog:

	* gdb.texinfo (GDB/MI Thread Information): Add missing
	fields, re-word some things.
	(GDB/MI Thread Commands): Describe fields found in the output of
	-thread-info, remove description of fields in the
	thread output tuple, replace with a cross-reference to "GDB/MI
	Thread Information".

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index efce1c0a11edfcb59bb334d1780bc49a7cfbac76..9be035c892793f5168189ed89355c6fae5c4dcef 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,12 @@
+2017-04-21  Simon Marchi  <simon.marchi@ericsson.com>
+
+       * gdb.texinfo (GDB/MI Thread Information): Add missing
+       fields, re-word some things.
+       (GDB/MI Thread Commands): Describe fields found in the output of
+       -thread-info, remove description of fields in the
+       thread output tuple, replace with a cross-reference to "GDB/MI
+       Thread Information".
+
 2017-04-21  Simon Marchi  <simon.marchi@ericsson.com>
 
        * gdb.texinfo (GDB/MI Thread Commands): Remove "current" field

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9e872763b271e165ecd84bd27a7e16a3f06e0a78..f2e615660edd45e28ed8d034dc530c63d5733a45 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26852,24 +26852,36 @@ corresponds to the frame's code address.  This field may be absent.
 @subsection @sc{gdb/mi} Thread Information
 
 Whenever @value{GDBN} has to report an information about a thread, it
-uses a tuple with the following fields:
+uses a tuple with the following fields.  The fields are always present unless
+stated otherwise.
 
 @table @code
 @item id
-The global numeric id assigned to the thread by @value{GDBN}.  This field is
-always present.
+The global numeric id assigned to the thread by @value{GDBN}.
 
 @item target-id
-Target-specific string identifying the thread.  This field is always present.
+The target-specific string identifying the thread.
 
 @item details
 Additional information about the thread provided by the target.
 It is supposed to be human-readable and not interpreted by the
 frontend.  This field is optional.
 
+@item name
+The name of the thread.  If the user specified a name using the
+@code{thread name} command, then this name is given.  Otherwise, if
+@value{GDBN} can extract the thread name from the target, then that
+name is given.  If @value{GDBN} cannot find the thread name, then this
+field is omitted.
+
 @item state
-Either @samp{stopped} or @samp{running}, depending on whether the
-thread is presently running.  This field is always present.
+The execution state of the thread, either @samp{stopped} or @samp{running},
+depending on whether the thread is presently running.
+
+@item frame
+The stack frame currently executing in the thread.  This field is only present
+if the thread is stopped.  Its format is documented in
+@ref{GDB/MI Frame Information}.
 
 @item core
 The value of this field is an integer number of the processor core the
@@ -28084,48 +28096,18 @@ about all threads.
 
 @subsubheading Result
 
-The result is a list of threads.  The following attributes are
-defined for a given thread:
+The result contains the following attributes:
 
 @table @samp
-@item id
-The global identifier that @value{GDBN} uses to refer to the thread.
-
-@item target-id
-The identifier that the target uses to refer to the thread.
-
-@item details
-Extra information about the thread, in a target-specific format.  This
-field is optional.
-
-@item name
-The name of the thread.  If the user specified a name using the
-@code{thread name} command, then this name is given.  Otherwise, if
-@value{GDBN} can extract the thread name from the target, then that
-name is given.  If @value{GDBN} cannot find the thread name, then this
-field is omitted.
-
-@item frame
-The stack frame currently executing in the thread.
-
-@item state
-The thread's state.  The @samp{state} field may have the following
-values:
-
-@table @code
-@item stopped
-The thread is stopped.  Frame information is available for stopped
-threads.
-
-@item running
-The thread is running.  There's no frame information for running
-threads.
-
-@end table
-
-@item core
-If @value{GDBN} can find the CPU core on which this thread is running,
-then this field is the core identifier.  This field is optional.
+@item threads
+A list of threads.  The format of the elements of the list is described in
+@ref{GDB/MI Thread Information}.
+
+@item current-thread-id
+The global id of the currently selected thread.  This field is omitted if there
+is no selected thread (for example, when the selected inferior is not running,
+and therefore has no threads) or if a @var{thread-id} argument was passed to
+the command.
 
 @end table