gnucash maint: Fix up and improve the Doxygen documentation in unittest-support.h.
John Ralls
jralls at code.gnucash.org
Tue Jul 28 15:44:32 EDT 2015
Updated via https://github.com/Gnucash/gnucash/commit/a4b05193 (commit)
from https://github.com/Gnucash/gnucash/commit/2663dc96 (commit)
commit a4b0519303834905aa783af14f37160db738d667
Author: John Ralls <jralls at ceridwen.us>
Date: Tue Jul 28 12:44:25 2015 -0700
Fix up and improve the Doxygen documentation in unittest-support.h.
diff --git a/src/test-core/unittest-support.h b/src/test-core/unittest-support.h
index fa4d07b..3497d90 100644
--- a/src/test-core/unittest-support.h
+++ b/src/test-core/unittest-support.h
@@ -25,11 +25,22 @@
#include <glib.h>
#include <qof.h>
+/** @file unittest-support.h
+ * @brief Macros and logging-capture functions to ease writing GLib-testing
+ * based unit tests.
+ */
+
+/** @name Unit Test Macros
+ * These macros facilitate combining a suite name and a test name to make a path
+ * when registering a test function with the corresponding g_test_add and
+ * g_test_add_func. Create a const char* suitename somewhere in the file and
+ * pass it as the first parameter, and the test name as the second. The
+ * remaining parameters are the same as in the underlying function.
+ */
/**
- * Use this macro to format informative test path output when using g_test_add.
- * Suite stands for tests' pack, while path for individual test name.
-*/
+ * Wraps gnc_test_add() for test functions needing a fixture.
+ */
#define GNC_TEST_ADD( suite, path, fixture, data, setup, test, teardown )\
{\
@@ -39,9 +50,8 @@
}
/**
- * Use this macro to format informative test path output when using g_test_add_func.
- * Suite stands for tests' pack, while path for individual test name.
-*/
+ * Wraps gnc_test_add_func() for test functions which don't require a fixture.
+ */
#define GNC_TEST_ADD_FUNC( suite, path, test )\
{\
@@ -49,9 +59,8 @@
g_test_add_func( testpath, test );\
g_free( testpath );\
}
-
-/**
- * Suppressing Expected Errors
+/** @} */
+/** @name Suppressing Expected Errors
*
* Functions for suppressing expected errors during tests. Pass
*
@@ -74,6 +83,7 @@
* NB: If you have more than one fatal error in a test function be
* sure to use the test_list_handler: You can have only one fatal
* handler.
+ * @{
*/
/**
@@ -115,6 +125,11 @@ TestErrorStruct* test_error_struct_new (gchar *log_domain,
*/
void test_error_struct_free (TestErrorStruct *);
+/**
+ * Holds a handler instance with its TestErrorStruct, handler id, and whether
+ * it's a list handler. A test fixture can be set up to hold a GSList of these
+ * so that they can be automatically unregistered and freed during teardown.
+ */
typedef struct
{
TestErrorStruct *error;
@@ -158,7 +173,9 @@ GSList *test_log_set_handler (GSList *list, TestErrorStruct *error,
GSList *test_log_set_fatal_handler (GSList *list, TestErrorStruct *error,
GLogFunc handler);
-/* Clears all the log handlers. Pass this to g_slist_free() in teardown */
+/**
+ * Clears all the log handlers. Pass this to g_slist_free() in teardown.
+ */
void test_free_log_handler (gpointer item);
/**
@@ -193,8 +210,7 @@ gboolean test_null_handler (const char *log_domain, GLogLevelFlags log_level,
* Call test_add_error for each TestErrorStruct to check against and
* test_clear_error_list when you no longer expect the errors.
*/
-void test_add_error (TestErrorStruct *error);
-void test_clear_error_list (void);
+void test_add_error (TestErrorStruct *error)voidvoid test_clear_error_list (void);
/**
* Checks received errors against the list created by
@@ -236,7 +252,14 @@ gpointer test_reset_data( void );
*/
void test_free( gpointer data );
-/* TestSignal is an opaque struct used to mock handling signals
+/** @}
+ */
+/** @name Test Signals
+ * Test the emission of signals from objects. Signals are used to coordinate the
+ * behavior of the GUI with events in other parts of the program. @{
+ */
+/**
+ * TestSignal is an opaque struct used to mock handling signals
* emitted by functions-under-test. It registers a handler and counts
* how many times it is called with the right instance and type. The
* struct is allocated using g_slice_new, and it registers a
@@ -249,30 +272,51 @@ void test_free( gpointer data );
* passed to test_signal_new should be NULL to avoid the test.
*/
typedef gpointer TestSignal;
+
+/**
+ * Create a test signal.
+ * @param entity: The QofInstance emitting the signal
+ * @param eventType: The type of the signal
+ * @param event_data: Any data required by the signal or NULL if none is.
+ * @return A newly created TestSignal. Use test_signal_free to release it.
+ */
+
TestSignal test_signal_new (QofInstance *entity, QofEventId eventType,
gpointer event_data);
-/* test_signal_return_hits gets the number of times the TestSignal has
- * been called.
+/**
+ * gets the number of times the TestSignal has been called.
*/
guint test_signal_return_hits (TestSignal sig);
-/* test_signal_assert_hits is a convenience macro which wraps
- * test_signal_return_hits with and equality assertion.
+/**
+ * Convenience macro which wraps test_signal_return_hits with and equality
+ * assertion.
*/
#define test_signal_assert_hits(sig, hits) \
g_assert_cmpint (test_signal_return_hits (sig), ==, hits)
+/**
+ * Free a test signal.
+ */
void test_signal_free (TestSignal sig);
-/* test_object_checked_destroy unrefs obj and returns true if its finalize
- * method was called.
+/** @}
+ */
+
+/** @name Testing for object disposal
+ * Sometimes we need to make sure that certain objects that we've created aren't leaking. These functions can help.
+ * @{
+ */
+
+/**
+ * Unrefs obj and returns true if its finalize method was called.
*/
gboolean test_object_checked_destroy (GObject *obj);
/**
- * test_destroy() ensures that a GObject is still alive at the time
+ * Ensures that a GObject is still alive at the time
* it's called and that it is finalized. The first assertion will
* trigger if you pass it a ponter which isn't a GObject -- which
* could be the case if the object has already been finalized. Then it
@@ -284,6 +328,7 @@ gboolean test_object_checked_destroy (GObject *obj);
g_assert (obj != NULL && G_IS_OBJECT (obj)); \
g_assert (test_object_checked_destroy (G_OBJECT (obj)))
+/** @} */
/* For Scheme testing access:
void gnc_log_init_filename_special (gchar *filename);
void gnc_log_shutdown (void);
diff --git a/test-templates/README b/test-templates/README
index 0a5a026..10d8fa6 100644
--- a/test-templates/README
+++ b/test-templates/README
@@ -40,4 +40,5 @@ and http://library.gnome.org/devel/glib/stable/glib-Testing.html
for detailed documentation.
There are some helpful macros and message-trapping functions in
-src/test-core/unittest-support.h.
+src/test-core/unittest-support.h, whose Doxygen documentation is at
+http://code.gnucash.org/docs/head/unittest-support_8h_source.html
Summary of changes:
src/test-core/unittest-support.h | 85 ++++++++++++++++++++++++++++++----------
test-templates/README | 3 +-
2 files changed, 67 insertions(+), 21 deletions(-)
More information about the gnucash-changes
mailing list