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

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

[Cyril Hrubis]

Fixes: #1162

Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
---
 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
+ *         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
-- 
2.44.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [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
> 





-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [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.

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Wei Gao via ltp]

 Tue, Oct 15, 2024 at 06:19:50PM +0200, Petr Vorel wrote:
> 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.
Reviewed-by: Wei Gao <wegao@suse.com>

> 
> -- 
> Mailing list info: https://lists.linux.it/listinfo/ltp

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Cyril Hrubis]

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

I know, fixed.

> > > 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"?

That is indeed better, thanks.

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

Fixed as well.

> > > + *         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"

AFAIK both can work here, so I kept the original.

Thanks a lot everyone for the reviews, pushed.

-- 
Cyril Hrubis
chrubis@suse.cz

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp