Re: [PATCH] Document board settting

[Eli Zaretskii <eliz at gnu dot org>]

> From: Yao Qi <yao@codesourcery.com>
> Date: Tue, 24 Apr 2012 23:05:56 +0800
> 
> This patch is to describe all the existing board settings we are using
> in GDB testsuite.  Some of them are obvious, but some are not.  I
> referred CVS log and mail archives to get the description to each
> of them.

Thank you!

> I comment out gdb,noresults and use_cygmon, which I can't figure out
> the purpose of using them.  I'll figure them out later.
> Please pay attention to my explanation to "gdb,nofileio" and
> "gdb,noinferiorio".  I am not satisfied with them, but unable
> to tell the difference of them.

> +@section Board settings
> +In @value{GDBN} testsuite, the tests can be configured or customized in its board file
                                                                        ^^^^^^^^^^^^^^^^^
"in the board file", I think.

> +file by means of @dfn{Boarding Settings}.
                         ^^^^^^^^^^^^^^^^^
I think you mean "Board Settings" here.

>                                           Here are the board settings,

I would rephrase

  Here are the supported board settings:

> +@item gdb,cannot_call_functions
> +Whether the board supports inferior call, that is, invoking inferior functions

Since it says "cannot", I think the meaning of this setting is that
inferior calls aren't supported.  So the "whether" part is not
appropriate.  Simply "the board does not support inferior calls" is
better.

> +in @value{GDBN}.  If inferior call is required in test case, this variable

  If inferior calls are required in a test case, ...

> +should be checked.
> +@item gdb,can_reverse
> +Whether the board supports reverse execution.

Again, it's better to say explicitly

  The board supports reverse execution.

>                                               If reverse execution is required
> +in test case, this variable should be checked.

Please fix this (and other similar places) as I suggested above.

Btw, I don't think it's a good idea to repeat the same sentence "If
FOO is required in a test case, this variable should be checked." for
every setting.  I think you should only state this once.

> +@item gdb_server_prog
> +The location of GDBserver.  If GDBserver somewhere other than its default
> +location is used in test, specify the location of GDBserver in this variable.

By "location" you mean the full file name, right?  If so, please say
so explicitly.  "Location" is ambiguous.