Documentation fixups

svn path=/trunk/; revision=7024

diff --git a/ChangeLog b/ChangeLog
index 1b3d9b5b0fbe8bec3f5390ec617f179679e6c904..6bb19a0506ceddac21321684ed8856d4b57c01fd 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-06-12  Matthias Clasen  <mclasen@redhat.com>
+
+       * glib/gtestutils.c: Documentation fixups
+
 2008-06-11  Matthias Clasen  <mclasen@redhat.com>
 
        * glib/glist.c: Tiny doc fix

diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index 23c5ae3ed616f5a1f48c8a4da39a288d90d0f4e5..cd7a2cd1edc35d335767d33627d1a1c1203b029b 100644 (file)
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -372,23 +372,77 @@ parse_args (gint    *argc_p,
  * test random number generator, the name for g_get_prgname()
  * and parsing test related command line args.
  * So far, the following arguments are understood:
- * <informalexample>
- * -l                   list test cases available in a test executable.
- * --seed RANDOMSEED    provide a random seed to reproduce test runs using random numbers.
- * --verbose            run tests verbosely.
- * -q, --quiet          run tests quietly.
- * -p TESTPATH          execute all tests matching TESTPATH.
- * -m {perf|slow|thorough|quick}
- *                      execute tests according to these test modes:
- *                      perf - performance tests, may take long and report results.
- *                      slow - slow and thorough tests, may take quite long and maximize coverage.
- *                      thorough - currently an alias for "slow".
- *                      quick - quick tests, should run really quickly and give good coverage.
- * --debug-log          debug test logging output.
- * -k, --keep-going     gtester specific argument.
- * --GTestLogFD N       gtester specific argument.
- * --GTestSkipCount N   gtester specific argument.
- * </informalexample>
+ * <variablelist>
+ *   <varlistentry>
+ *     <term><option>-l</option></term>
+ *     <listitem><para>
+ *       list test cases available in a test executable.
+ *     </para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
+ *     <listitem><para>
+ *       provide a random seed to reproduce test runs using random numbers.
+ *     </para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>--verbose</option></term>
+ *       <listitem><para>run tests verbosely.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>-q</option>, <option>--quiet</option></term>
+ *       <listitem><para>run tests quietly.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>-p <replaceable>TESTPATH</replaceable></option></term>
+ *       <listitem><para>
+ *         execute all tests matching <replaceable>TESTPATH</replaceable>.
+ *       </para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>-m {perf|slow|thorough|quick}</option></term>
+ *       <listitem><para>
+ *         execute tests according to these test modes:
+ *         <variablelist>
+ *           <varlistentry>
+ *             <term>perf</term>
+ *             <listitem><para>
+ *               performance tests, may take long and report results.
+ *             </para></listitem>
+ *           </varlistentry>
+ *           <varlistentry>
+ *             <term>slow, thorough</term>
+ *             <listitem><para>
+ *               slow and thorough tests, may take quite long and 
+ *               maximize coverage.
+ *             </para></listitem>
+ *           </varlistentry>
+ *           <varlistentry>
+ *             <term>quick</term>
+ *             <listitem><para>
+ *               quick tests, should run really quickly and give good coverage.
+ *             </para></listitem>
+ *           </varlistentry>
+ *         </variablelist>
+ *       </para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>--debug-log</option></term>
+ *       <listitem><para>debug test logging output.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>-k</option>, <option>--keep-going</option></term>
+ *       <listitem><para>gtester-specific argument.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>--GTestLogFD <replaceable>N</replaceable></option></term>
+ *       <listitem><para>gtester-specific argument.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *       <term><option>--GTestSkipCount <replaceable>N</replaceable></option></term>
+ *       <listitem><para>gtester-specific argument.</para></listitem>
+ *     </varlistentry>
+ *  </variablelist>
  *
  * Since: 2.16
  */
@@ -485,9 +539,11 @@ test_run_seed (const gchar *rseed)
  * g_test_rand_int:
  *
  * Get a reproducible random integer number.
+ *
  * The random numbers generated by the g_test_rand_*() family of functions
  * change with every new test program start, unless the --seed option is
  * given when starting test programs.
+ *
  * For individual test cases however, the random number generator is
  * reseeded, to avoid dependencies between tests and to make --seed
  * effective for all test cases.
@@ -689,6 +745,7 @@ g_test_message (const char *format,
  * @uri_pattern: the base pattern for bug URIs
  *
  * Specify the base URI for bug reports.
+ *
  * The base URI is used to construct bug report messages for
  * g_test_message() when g_test_bug() is called.
  * Calling this function outside of a test case sets the
@@ -1118,7 +1175,8 @@ g_test_run_suite_internal (GTestSuite *suite,
  *
  * Execute the tests within @suite and all nested #GTestSuites.
  * The test suites to be executed are filtered according to
- * test path arguments (-p <testpath>) as parsed by g_test_init().
+ * test path arguments (-p <replaceable>testpath</replaceable>) 
+ * as parsed by g_test_init().
  * g_test_run_suite() or g_test_run() may only be called once
  * in a program.
  *
@@ -1430,22 +1488,40 @@ test_time_stamp (void)
  * Fork the current test program to execute a test case that might
  * not return or that might abort. The forked test case is aborted
  * and considered failing if its run time exceeds @usec_timeout.
+ *
  * The forking behavior can be configured with the following flags:
- * %G_TEST_TRAP_SILENCE_STDOUT - redirect stdout of the test child
- * to /dev/null so it cannot be observed on the console during test
- * runs. The actual output is still captured though to allow later
- * tests with g_test_trap_assert_stdout().
- * %G_TEST_TRAP_SILENCE_STDERR - redirect stderr of the test child
- * to /dev/null so it cannot be observed on the console during test
- * runs. The actual output is still captured though to allow later
- * tests with g_test_trap_assert_stderr().
- * %G_TEST_TRAP_INHERIT_STDIN - if this flag is given, stdin of the
- * forked child process is shared with stdin of its parent process.
- * It is redirected to /dev/null otherwise.
+ * <variablelist>
+ *   <varlistentry>
+ *     <term>%G_TEST_TRAP_SILENCE_STDOUT</term>
+ *     <listitem><para>
+ *       redirect stdout of the test child to <filename>/dev/null</filename> 
+ *       so it cannot be observed on the console during test runs. 
+ *       The actual output is still captured though to allow later
+ *       tests with g_test_trap_assert_stdout().
+ *     </para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>%G_TEST_TRAP_SILENCE_STDERR</term>
+ *     <listitem><para>
+ *       redirect stderr of the test child to <filename>/dev/null</filename>
+ *       so it cannot be observed on the console during test runs. 
+ *       The actual output is still captured though to allow later
+ *       tests with g_test_trap_assert_stderr().
+ *     </para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>%G_TEST_TRAP_INHERIT_STDIN</term>
+ *     <listitem><para>
+ *       if this flag is given, stdin of the forked child process is 
+ *       shared with stdin of its parent process. It is redirected to 
+ *       <filename>/dev/null</filename> otherwise.
+ *     </para></listitem>
+ *   </varlistentry>
+ * </variablelist>
  *
  * In the following example, the test code forks, the forked child
  * process produces some sample output and exits successfully.
- * The forking parent process then asserts successfull child program
+ * The forking parent process then asserts successful child program
  * termination and validates child program outputs.
  *
  * |[