Re: [PATCH] Add comment for mi_run_cmd_full

[Joel Brobecker <brobecker at adacore dot com>]

Hi Simon,

> 2014-05-21  Simon Marchi  <simon.marchi@ericsson.com>
> 
> 	* lib/mi-support.exp (mi_run_cmd_full): Add comments.

Overall, this looks good to me. I wasn't aware of the history,
so just did a little bit of catching up :-), but I confirm that
the description you propose matches the actual behavior...

> +# use_mi_command selects whether MI or CLI commands are used by the
> +# procedure.
> +# args is passed to the command used to run the test program, "run" or
> +# "-exec-run", depending on the value of use_mi_command. Therefore, if
> +# use_mi_command is false, they are effectively args to the test program.
> +# If use_mi_command is true, they are simply arguments to -exec-run.
>  proc mi_run_cmd_full {use_mi_command args} {
>      global suppress_flag
>      if { $suppress_flag } {
> -- 
> 2.0.0.rc0

When speaking of the value of a variable, the variable name should be
in all caps. For instance:

# USE_MI_COMMAND selects whether MI or CLI commands are used by the
# procedure.

If I may suggest a different approach (anyone is welcome to comment
on that too), it'd be useful to succintly say what the function does
first, before getting into the details of the parameters. Also, I would
group the semantics of each value of use_mi_command together. So,
one example:

# Send the command to run the test program.
#
# If USE_MI_COMMAND is true, the "-exec-run" command is used.
# Otherwise, the "run" (CLI) command is used.
#
# ARGS is passed as argument to the command used to run the test program.
# Beware that arguments to "-exec-run" do not have the same semantics as
# arguments to the "run" command, so USE_MI_COMMAND influences the meaning
# of ARGS. If USE_MI_COMMAND is true, they are arguments to -exec-run.
# If USE_MI_COMMAND is false, they are effectively arguments passed
# to the test program.

I hope it helps!
-- 
Joel