Document do_test in test-skeleton.c

	* test-skeleton.c: Document do_test usage.

2 files changed, 20 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index afe2254a64..1ac8d2c2dd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2016-11-07  Steve Ellcey  <sellcey@caviumnetworks.com>
+
+	* test-skeleton.c: Document do_test usage.
+
 2016-11-06  Aurelien Jarno  <aurelien@aurel32.net>
 
 	* iconv/gconv.h (__gconv_info): Define __data element using a
diff --git a/test-skeleton.c b/test-skeleton.c
index 55841fbbdf..fa457befa5 100644
--- a/test-skeleton.c
+++ b/test-skeleton.c
@@ -36,7 +36,22 @@
 
 /* The test function is normally called `do_test' and it is called
    with argc and argv as the arguments.  We nevertheless provide the
-   possibility to overwrite this name.  */
+   possibility to overwrite this name.
+
+   The TEST_FUNCTION expression should have a type of 'int' and should
+   return 0 to indicate a passing test, 1 to indicate a failing test,
+   or 77 to indicate an unsupported test.  Other result values could be
+   used to indicate a failing test, but the result of the expression
+   is passed to exit and exit only returns the lower 8 bits of its input.
+   A non-zero return with some values could cause a test to incorrectly
+   be considered passing when it really failed. For this reason the
+   expression should always return 0, 1, or 77.
+
+   The test function may print out diagnostic or warning messages as well
+   as messages about failures.  These messages should be printed to stdout
+   and not stderr so that the output is properly ordered with respect to
+   the rest of the glibc testsuite run output.  */
+
 #ifndef TEST_FUNCTION
 # define TEST_FUNCTION do_test (argc, argv)
 #endif