stdcxx-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From se...@apache.org
Subject svn commit: r279149 - /incubator/stdcxx/trunk/tests/include/driver.h
Date Tue, 06 Sep 2005 22:07:53 GMT
Author: sebor
Date: Tue Sep  6 15:07:52 2005
New Revision: 279149

URL: http://svn.apache.org/viewcvs?rev=279149&view=rev
Log:
2005-09-06  Martin Sebor  <sebor@roguewave.com>

	* driver.h: Added Doxygen-style documentation.

Modified:
    incubator/stdcxx/trunk/tests/include/driver.h

Modified: incubator/stdcxx/trunk/tests/include/driver.h
URL: http://svn.apache.org/viewcvs/incubator/stdcxx/trunk/tests/include/driver.h?rev=279149&r1=279148&r2=279149&view=diff
==============================================================================
--- incubator/stdcxx/trunk/tests/include/driver.h (original)
+++ incubator/stdcxx/trunk/tests/include/driver.h Tue Sep  6 15:07:52 2005
@@ -22,36 +22,150 @@
 #ifndef RW_DRIVER_H_INCLUDED
 #define RW_DRIVER_H_INCLUDED
 
-#include <rw/_defs.h>   // for libstd config macros
 #include <testdefs.h>   // for test config macros
 
 
-_TEST_EXPORT int
-rw_test (int, char*[], const char*, const char*, const char*,
-         int (*)(int, char**), const char*, ...);
-
-_TEST_EXPORT int
-rw_fatal (int, const char*, int, const char*, ...);
-
+/**
+ * Initializes the test driver, passes program arguments to it, processes
+ * command line arguments, any arguments specified in the environment
+ * variable RWSTD_TESTOPTS, and if successful, invokes the program-supplied
+ * callback function.
+ *
+ * @param argc  The number of non-null elements in the argv array.
+ * @param argv  A null-terminated array of command line arguments.
+ *        If (argc == 0) the argument may be null.
+ * @param filename  The name of the source file name, typically
+ *        the __FILE__ macro. The argument may be null.
+ * @param clause  The clause exercised by the program, such as
+ *        lib.basic.string. The argument may be null.
+ * @param comment An optional comment describing in more detail
+ *        the functionality of the program. The argument may be null.
+ * @param testfun  A pointer to a callback function to call by the
+ *        driver after successful initialization. The argument must
+ *        not be null.
+ * @param optspec An optional character string describing command
+ *        line options accepted by the program. The argument may
+ *        be null.
+ * @param ...  Optional list of handlers of command line options
+ *         corresponding to the optspec.
+ *
+ * @return If initialization is successful, returns the value returned
+ *         by the callback function. Otherwise, returns the non-zero
+ *         value returned by the last initialization function or
+ *         command line option handler.
+ *
+ * After the driver has been initialzied the user-supplied callback function
+ * may call any of the driver diagnostic functions to record and perhaps also
+ * issue diagnostic messages of varying severity.
+ *
+ * There are 10 levels of severity with 0 being the lowest and 9 the highest.
+ * Diagnostics of all levels of severity come in two states: active and
+ * inactive. All diagnostics are recorded but normally only active diagnostics
+ * of severity 4 or above are issued. It is possible to cause diagnostics of
+ * lower severity levels to be issued via a command line option to the driver.
+ * Choosing to issue severity 0 diagnostics has the effect of issuing inactive
+ * diagnostics.
+ *
+ * After the callback function returns the driver displays a summary detailing
+ * the number of recorded diagnostics in each of the two states (active and
+ * inactive).
+ * 
+ */
+_TEST_EXPORT int
+rw_test (int           argc,
+         char*         argv[],
+         const char*   filename,
+         const char*   clause,
+         const char*   comment,
+         int         (*testfun)(int, char**),
+         const char*   optspec,
+         ...);
+
+/**
+ * Records and optionally issues a diagnostic of the highest severity 9.
+ *
+ * @param expr  A zero value denoting an active diagnostic or any non-zero
+ *        vaue denoting an inactive diagnostic.
+ * @param filename  An optional name of the file invoking the function.
+ *        The argument may be null.
+ * @param line  When positive, denotes the line number of the location
+ *        relevant to the diagnostic. Negative values are ignored.
+ * @param fmtspec  A printf format specifier (with extensions) used
+ *        to format the text of the diagnostic.
+ * @param ... Optional list of values to format.
+ *
+ * @return  Returns the value of expr passed to it.
+ *
+ * Every diagnostic is recorded but only active diagnostics may be issued,
+ * depending on the setting of the diagnosable severity. The value of the
+ * first argument determines whether a diagnostc is active or inactive.
+ * Unlike the remaining diagnostic functions, rw_fatal doesn't return to
+ * the caller when expr is 0 (i.e., when the diagnostic is active).
+ * Instead, it causes the driver the exit the process with the staus equal
+ * to 9, the severity of the diagnostic.
+ */
+_TEST_EXPORT int
+rw_fatal (int         expr,
+          const char* filename,
+          int         line,
+          const char* fmtspec,
+          ...);
+
+/**
+ * Records and optionally issues a diagnostic of severity 8.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_error (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 7.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_assert (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 6.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_warn (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 5.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_note (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 4.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_info (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 2.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_debug (int, const char*, int, const char*, ...);
 
+/**
+ * Records and optionally issues a diagnostic of severity 1.
+ *
+ * @see #rw_fatal
+ */
 _TEST_EXPORT int
 rw_trace (int, const char*, int, const char*, ...);
+
 
 #endif   // RW_DRIVER_H_INCLUDED



Mime
View raw message