[LTP] [PATCH v2 5/8] doc: Document TEST macro and state TST_RET/ERR rule LTP-002

[Petr Vorel <pvorel@suse.cz>]

Hi Richie,

generally LGTM, with comments below.

Reviewed-by: Petr Vorel <pvorel@suse.cz>

> There are cases where these variables can be safely used by the
> library. However it is a difficult problem to identify these cases
> automatically.

> Identifying any library code which uses them is relatively easy. In
> fact it is easier to automate it than by code review. Because it is
> such a boring thing to repeatedly look for and comment on.

> If a test library function needs these variables it can recreate its
> own private copies.

> Signed-off-by: Richard Palethorpe <rpalethorpe@suse.com>
> ---
>  doc/c-test-api.txt                     | 47 ++++++++++++++++++++++++++
>  doc/library-api-writing-guidelines.txt | 14 ++++++++
>  2 files changed, 61 insertions(+)

> diff --git a/doc/c-test-api.txt b/doc/c-test-api.txt
> index 45784195b..b47728f60 100644
> --- a/doc/c-test-api.txt
> +++ b/doc/c-test-api.txt
> @@ -767,6 +767,53 @@ LTP_ALIGN(x, a)

>  Aligns the x to be next multiple of a. The a must be power of 2.

> +[source,c]
> +-------------------------------------------------------------------------------
> +TEST(socket(AF_INET, SOCK_RAW, 1));
> +if (TST_RET > -1) {
> +	tst_res(TFAIL, "Created raw socket");
> +	SAFE_CLOSE(TST_RET);
> +} else if (TST_ERR != EPERM) {
> +	tst_res(TFAIL | TTERRNO,
> +		"Failed to create socket for wrong reason");
> +} else {
> +	tst_res(TPASS | TTERRNO, "Didn't create raw socket");
> +}
> +-------------------------------------------------------------------------------
> +
> +The +TEST+ macro sets +TST_RET+ to its argument's return value and
> ++TST_ERR+ to +errno+. The +TTERNO+ flag can be used to print the error
> +number's symbolic value.
Nice examples, but we already talk about TEST() in "1.2 Basic test interface".
Should we put it there? If not, I'd add links to both places to the other
(separate effort).
Also I suppose whole thing could be simplified with TST_EXP_FAIL2().

> +
> +No LTP library function or macro, except those in 'tst_test_macros.h',
> +will write to these variables (rule 'LTP-002'). So their values will
> +not be changed unexpectedly.
> +
> +[source,c]
> +-------------------------------------------------------------------------------
> +TST_EXP_POSITIVE(wait(&status));
> +
> +if (!TST_PASS)
> +	return;
IMHO This is really for "1.2 Basic test interface".

> +-------------------------------------------------------------------------------
> +
> +If the return value of 'wait' is positive. This macro will print a
> +pass result and set +TST_PASS+ appropriately. If the return value is
> +zero or negative, then it will print fail.
> +
> +This and similar macros take optional variadic arguments. These begin
> +with a format string and then appropriate values to be formatted.
> +
> +[source,c]
> +-------------------------------------------------------------------------------
> +TST_EXP_PASS(chown("a/file", uid, gid), "chown(%s,%d,%d)",
> +	     "a/file", uid, gid);
> +-------------------------------------------------------------------------------
> +
> +Expects +chown+ to return 0 and emits a pass or a fail. The arguments
> +to +chown+ will be printed in either case. There are many similar
> +macros, please see 'tst_test_macros.h'.
And this as well.

...

> diff --git a/doc/library-api-writing-guidelines.txt b/doc/library-api-writing-guidelines.txt
> index a4393fc54..2819d4177 100644
> --- a/doc/library-api-writing-guidelines.txt
> +++ b/doc/library-api-writing-guidelines.txt
> @@ -21,10 +21,24 @@ Don't forget to update docs when you change the API.
>  2. C API
>  --------

> +2.1 LTP-001: Sources have tst_ prefix
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1

> +
>  API source code is in headers `include/*.h`, `include/lapi/*.h` (backward
>  compatibility for old kernel and libc) and C sources in `lib/*.c`. Files have
>  'tst_' prefix.

> +2.2 LTP-002: TST_RET and TST_ERR are not modified
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The test author is guaranteed that the test API will not modify these
> +variables. This prevents silent errors where the return value and
> +errno are overwritten before the test has chance to check them.
> +
> +The macros which are clearly intended to update these variables. That
> +is +TEST+ and those in 'tst_test_macros.h'. Are of course allowed to
nit: Maybe +TEST()+ (it's a "function", unlike "variables" TST_RET TST_ERR)?

> +update these variables.

Kind regards,
Petr