[PATCH 1/9] tests: Update the documentation.

[Francois Gouget]

From: Francois Gouget

---
 include/wine/test.h | 37 ++++++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/include/wine/test.h b/include/wine/test.h
index c28128d9f0c..c20c6736e2b 100644
--- a/include/wine/test.h
+++ b/include/wine/test.h
@@ -280,6 +280,13 @@ static void exit_process( int code )
 }

+/* Records the location of the next check.
+ * See the xxx_(file, line) macros.
+ *
+ * Parameters:
+ *   - file - source file name of the check
+ *   - line - source line number of the check
+ */
 void winetest_set_location( const char* file, int line )
 {
     struct tls_data *data = get_tls_data();
@@ -391,12 +398,13 @@ static LONG winetest_add_line( void )
 }

/*
- * Checks condition.
+ * Checks that a condition has the expected value, that is true except if
+ * preceded by a todo indicating the check is expected to fail.
+ *
  * Parameters:
- *   - condition - condition to check;
- *   - msg test description;
- *   - file - test application source code file name of the check
- *   - line - test application source code file line number of the check
+ *   - condition - true if the check succeeded, false otherwise;
+ *   - msg - failure message format;
+ *   - args - arguments for the failure message
  * Return:
  *   0 if condition does not have the expected value, 1 otherwise
  */
@@ -551,6 +559,18 @@ void winetest_win_skip( const char *msg, ... )
     va_end(valist);
 }

+/* If is_flaky is true, indicates that the next test may occasionally fail due
+ * to unavoidable outside race conditions. Such failures will be flagged as
+ * flaky so they can be ignored by automated testing tools.
+ *
+ * Notes:
+ * - This is not meant to paper over race conditions within the test itself.
+ *   Those are bugs and should be fixed.
+ * - This is not meant to be used for tests that normally succeed but
+ *   systematically fail on a specific platform or locale.
+ * - The failures should be rare to start with. If a test fails 25% of the time
+ *   it is probably wrong to start with.
+ */
 void winetest_start_flaky( int is_flaky )
 {
     struct tls_data *data = get_tls_data();
@@ -572,6 +592,13 @@ void winetest_end_flaky(void)
     data->flaky_level >>= 1;
 }

+/* If is_todo is true, indicates that the next test is expected to fail on this
+ * platform. This used to identify tests that are known to fail in Wine.
+ *
+ * Notes:
+ * - is_todo should never be true on Windows. To ensure this, always use
+ *   todo_wine_if().
+ */
 void winetest_start_todo( int is_todo )
 {
     struct tls_data *data = get_tls_data();