[LTP] [PATCH] include: Better documentation for TFAIL and TBROK\

[Avinesh Kumar]

Hi Cyril,

On Friday, September 27, 2024 12:18:13 PM GMT+2 Cyril Hrubis wrote:
> Fixes: #1162
> 
> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>

Reviewed-by: Avinesh Kumar <akumar@suse.de>

Thank you,
Avinesh

> ---
>  include/tst_res_flags.h | 23 +++++++++++++++++++----
>  1 file changed, 19 insertions(+), 4 deletions(-)
> 
> diff --git a/include/tst_res_flags.h b/include/tst_res_flags.h
> index 806940e0d..a79428fa2 100644
> --- a/include/tst_res_flags.h
> +++ b/include/tst_res_flags.h
> @@ -9,11 +9,26 @@
>  /**
>   * enum tst_res_flags - Test result reporting flags.
>   *
> - * @TPASS: Reports a single success.
> - * @TFAIL: Reports a single failure.
> - * @TBROK: Reports a single breakage.
> + * @TPASS: Reports a single success. Successes increment passed counter and
> + *         show up in the test results.
> + *
> + * @TFAIL: Reports a single failure. Failures increment failure counter and
> + *         show up in the test results. A failure occurs when test assertion
> + *         is broken.
> + *
> + * @TBROK: Reports a single breakage. Breakages increment breakage counter and
> + *         show up in the test results. Breakages are reported in cases where a
> + *         test couldn't be executed due to an unexpected failure when we were
> + *         setting the test environment. The TBROK status is mostly used
> + *         with tst_brk() which exit the test immediatelly. The difference
s/immediatelly/immediately 

> + *         between TBROK and TCONF is that TCONF is used in cases where
> + *         optional functionality is missing while TBROK is used in cases where
> + *         something that is supposed to work is broken unexpectedly.
> + *
>   * @TWARN: Reports a single warning. Warnings increment a warning counter and
> - *         show up in test results.
> + *         show up in test results. Warnings are somewhere in the middle between
> + *         TBROK and TCONF. Warnings usually appear when something that is
> + *         supposed to be working is broken but the test can somehow continue.
>   *
>   * @TDEBUG: Prints additional debugging messages, it does not change the test result counters and
>   *          the message is not displayed unless debugging is enabled with -D
>