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

[Petr Vorel]

Hi Cyril, Avinesh,

nit: there is trailing "\" in the test subject.

> 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
nit: maybe use passive form? "when we were setting the test environment" =>
"during the test setup" or "during setting the test environment"?

> > + *         setting the test environment. The TBROK status is mostly used
> > + *         with tst_brk() which exit the test immediatelly. The difference
> s/immediatelly/immediately 

+1

> > + *         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.
nit (not really sure): "that" => "which"

> > + *
> >   * @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
nit (not really sure): "that" => "which"

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

Kind regards,
Petr

> > + *         supposed to be working is broken but the test can somehow continue.