[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