Re: [PATCH] gdb: improve usage strings

Eli Zaretskii
2012-08-11T17:16:32Z

> From: Mike Frysinger <vapier@gentoo.org>
> Date: Sat, 11 Aug 2012 12:54:40 -0400
>
> This adds Usage strings to a bunch of commands, tweaks the grammar in a
> few, and improves the help text for the handle command.

Thanks.

> c = add_com ("signal", class_run, signal_command, _("\
> -Continue program giving it signal specified by the argument.\n\
> -An argument of \"0\" means continue program without giving it a signal."));
> +Continue program by sending it the specified signal.\n\

This "by sending it" is AFAIU inaccurate: we don't continue program
_by_ sending it the signal, we continue the program _and_ send it the
signal. I actually don't see anything wrong with the original
wording.

> add_com ("finish", class_run, finish_command, _("\
> Execute until selected stack frame returns.\n\
> +Usage: finish\n\
> Upon return, the value returned is printed and put in the value history."));

Does this "usage" really add any information?

> add_com ("next", class_run, next_command, _("\
> Step program, proceeding through subroutine calls.\n\
> +Usage: next [N]\n\
> Like the \"step\" command as long as subroutine calls do not happen;\n\
> when they do, the call is treated as one instruction.\n\
> -Argument N means do this N times (or till program stops for another \
> +Argument N means step N times (or till program stops for another \

Isn't it better to say "N source lines"?

Btw, I find this entire doc string completely obfuscated. How about
this instead:

Step program until it reaches a different source line.
Usage: next [N]
Unlike "step", if the current source line calls a subroutine,
this command does not enter the subroutine, but instead steps over
the call, in effect treating it as a single source line.