diff mbox

[RFA,01/12] Fix help and documentation for inferior commands

Message ID 20180430143731.30007-2-tom@tromey.com
State New, archived
Headers

Commit Message

Tom Tromey April 30, 2018, 2:37 p.m. UTC 
  This changes inferior.c to add Usage lines for all commands, and to
change how "metasyntactic variables" are written to conform to GNU
style.

While doing this I noticed that the manual doesn't document the
argument to "info inferiors", so I've added that as well.

ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* inferior.c (initialize_inferiors): Update help strings.

doc/ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* gdb.texinfo (Inferiors and Programs): Document argument to "info
	inferiors".
---
 gdb/ChangeLog       |  4 ++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo |  4 +++-
 gdb/inferior.c      | 18 ++++++++++++------
 4 files changed, 24 insertions(+), 7 deletions(-)

Comments

Eli Zaretskii April 30, 2018, 3:26 p.m. UTC | #1 
> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Mon, 30 Apr 2018 08:37:20 -0600
> 
> While doing this I noticed that the manual doesn't document the
> argument to "info inferiors", so I've added that as well.

Thanks.

>  @table @code
> -@kindex info inferiors
> +@kindex info inferiors [ @var{ID}@dots{} ]

"ID" should be in lower-case.  (It will be rendered in caps in Info,
but not in the printed output, where it will be typeset in the slant
typeface.)

> +By default all inferiors are printed, but an argument can be used to
> +limit the display to just the requested inferiors.

This should reference @var{id} and explain what the "id" there is.
Someone might think it's a PID, for example.
Pedro Alves May 4, 2018, 6:07 p.m. UTC | #2 
On 04/30/2018 04:26 PM, Eli Zaretskii wrote:
>> From: Tom Tromey <tom@tromey.com>
>> Cc: Tom Tromey <tom@tromey.com>
>> Date: Mon, 30 Apr 2018 08:37:20 -0600
>>
>> While doing this I noticed that the manual doesn't document the
>> argument to "info inferiors", so I've added that as well.
> 
> Thanks.
> 
>>  @table @code
>> -@kindex info inferiors
>> +@kindex info inferiors [ @var{ID}@dots{} ]
> 
> "ID" should be in lower-case.  (It will be rendered in caps in Info,
> but not in the printed output, where it will be typeset in the slant
> typeface.)
> 
>> +By default all inferiors are printed, but an argument can be used to
>> +limit the display to just the requested inferiors.
> 
> This should reference @var{id} and explain what the "id" there is.
> Someone might think it's a PID, for example.

I think it'll also to good to say that it's a space-separated
list of IDs, like we say in the "info threads" help and documentation.
See thread-id-list / "thread ID lists", and "breakpoint lists" in
the manual for examples.

Thanks,
Pedro Alves
Tom Tromey May 9, 2018, 8:29 p.m. UTC | #3 
>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tom Tromey <tom@tromey.com>
>> Cc: Tom Tromey <tom@tromey.com>
>> Date: Mon, 30 Apr 2018 08:37:20 -0600
>> 
>> While doing this I noticed that the manual doesn't document the
>> argument to "info inferiors", so I've added that as well.

Eli> Thanks.

>> @table @code
>> -@kindex info inferiors
>> +@kindex info inferiors [ @var{ID}@dots{} ]

Eli> "ID" should be in lower-case.  (It will be rendered in caps in Info,
Eli> but not in the printed output, where it will be typeset in the slant
Eli> typeface.)

>> +By default all inferiors are printed, but an argument can be used to
>> +limit the display to just the requested inferiors.

Eli> This should reference @var{id} and explain what the "id" there is.
Eli> Someone might think it's a PID, for example.

How about like this:

    @kindex info inferiors [ @var{id}@dots{} ]
    @item info inferiors
    Print a list of all inferiors currently being managed by @value{GDBN}.
    By default all inferiors are printed, but the argument -- a space
    separate list of inferior numbers -- can be used to limit the display
    to just the requested inferiors.

This doesn't refer to @var{id} but I didn't see a clean way to do that.

Tom
Eli Zaretskii May 10, 2018, 2:31 a.m. UTC | #4 
> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>,  gdb-patches@sourceware.org
> Date: Wed, 09 May 2018 14:29:28 -0600
> 
> >> @table @code
> >> -@kindex info inferiors
> >> +@kindex info inferiors [ @var{ID}@dots{} ]
> 
> Eli> "ID" should be in lower-case.  (It will be rendered in caps in Info,
> Eli> but not in the printed output, where it will be typeset in the slant
> Eli> typeface.)
> 
> >> +By default all inferiors are printed, but an argument can be used to
> >> +limit the display to just the requested inferiors.
> 
> Eli> This should reference @var{id} and explain what the "id" there is.
> Eli> Someone might think it's a PID, for example.
> 
> How about like this:
> 
>     @kindex info inferiors [ @var{id}@dots{} ]
>     @item info inferiors
>     Print a list of all inferiors currently being managed by @value{GDBN}.
>     By default all inferiors are printed, but the argument -- a space
>     separate list of inferior numbers -- can be used to limit the display
>     to just the requested inferiors.

Yes, thanks.

> This doesn't refer to @var{id} but I didn't see a clean way to do that.

Like this:

  ... but the argument @var{id}@dots{} -- a space separated list ...

(Note: "separated", not "separate".)
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 28f083f96e..a25ada6e28 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2708,9 +2708,11 @@  To find out what inferiors exist at any moment, use @w{@code{info
 inferiors}}:
 
 @table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{ID}@dots{} ]
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but an argument can be used to
+limit the display to just the requested inferiors.
 
 @value{GDBN} displays for each inferior (in this order):
 
diff --git a/gdb/inferior.c b/gdb/inferior.c
index d7122fcfad..ec2f985919 100644
--- a/gdb/inferior.c
+++ b/gdb/inferior.c
@@ -996,12 +996,15 @@  initialize_inferiors (void)
   /* The architecture will be initialized shortly, by
      initialize_current_architecture.  */
 
-  add_info ("inferiors", info_inferiors_command, 
-	    _("IDs of specified inferiors (all inferiors if no argument)."));
+  add_info ("inferiors", info_inferiors_command,
+	    _("Print a list of inferiors being managed.\n\
+Usage: info inferiors [ID]...\n\
+If IDs are specified, the list is limited to just those inferiors.\n\
+By default all inferiors are displayed."));
 
   c = add_com ("add-inferior", no_class, add_inferior_command, _("\
 Add a new inferior.\n\
-Usage: add-inferior [-copies <N>] [-exec <FILENAME>]\n\
+Usage: add-inferior [-copies N] [-exec FILENAME]\n\
 N is the optional number of inferiors to add, default is 1.\n\
 FILENAME is the file name of the executable to use\n\
 as main program."));
@@ -1013,22 +1016,25 @@  Usage: remove-inferiors ID..."));
 
   add_com ("clone-inferior", no_class, clone_inferior_command, _("\
 Clone inferior ID.\n\
-Usage: clone-inferior [-copies <N>] [ID]\n\
+Usage: clone-inferior [-copies N] [ID]\n\
 Add N copies of inferior ID.  The new inferior has the same\n\
 executable loaded as the copied inferior.  If -copies is not specified,\n\
 adds 1 copy.  If ID is not specified, it is the current inferior\n\
 that is cloned."));
 
   add_cmd ("inferiors", class_run, detach_inferior_command, _("\
-Detach from inferior ID (or list of IDS)."),
+Detach from inferior ID (or list of IDS).\n\
+Usage; detach inferiors ID..."),
 	   &detachlist);
 
   add_cmd ("inferiors", class_run, kill_inferior_command, _("\
-Kill inferior ID (or list of IDs)."),
+Kill inferior ID (or list of IDs).\n\
+Usage: kill inferiors ID..."),
 	   &killlist);
 
   add_cmd ("inferior", class_run, inferior_command, _("\
 Use this command to switch between inferiors.\n\
+Usage: inferior ID\n\
 The new inferior ID must be currently known."),
 	   &cmdlist);