r15576 - gnucash/trunk/lib/libqof/qof - Update qoflog documentation.
Josh Sled
jsled at cvs.gnucash.org
Tue Feb 13 19:59:41 EST 2007
Author: jsled
Date: 2007-02-13 19:59:40 -0500 (Tue, 13 Feb 2007)
New Revision: 15576
Trac: http://svn.gnucash.org/trac/changeset/15576
Modified:
gnucash/trunk/lib/libqof/qof/qof.h
gnucash/trunk/lib/libqof/qof/qoflog.h
Log:
Update qoflog documentation.
Modified: gnucash/trunk/lib/libqof/qof/qof.h
===================================================================
--- gnucash/trunk/lib/libqof/qof/qof.h 2007-02-13 21:03:59 UTC (rev 15575)
+++ gnucash/trunk/lib/libqof/qof/qof.h 2007-02-14 00:59:40 UTC (rev 15576)
@@ -54,10 +54,6 @@
@addtogroup Query Query: Querying for Objects
@ingroup QOF
*/
-/**
- @addtogroup Trace Trace: Error Reporting and Debugging
- @ingroup QOF
-*/
/** @addtogroup Event Event: QOF event handlers.
@ingroup QOF
*/
Modified: gnucash/trunk/lib/libqof/qof/qoflog.h
===================================================================
--- gnucash/trunk/lib/libqof/qof/qoflog.h 2007-02-13 21:03:59 UTC (rev 15575)
+++ gnucash/trunk/lib/libqof/qof/qoflog.h 2007-02-14 00:59:40 UTC (rev 15576)
@@ -1,11 +1,10 @@
-/***************************************************************************
- * qof-log.h
- *
- * Author: Rob Clark (rclark at cs.hmc.edu)
- * Copyright (C) 1998-2003 Linas Vepstas <linas at linas.org>
- * Copyright 2005 Neil Williams <linux at codehelp.co.uk>
- * Copyright 2007 Joshua Sled <jsled at asynchronous.org>
- ****************************************************************************/
+/* qof-log.h
+ * Author: Rob Clark <rclark at cs.hmc.edu>
+ * Copyright (C) 1998-2003 Linas Vepstas <linas at linas.org>
+ * Copyright 2005 Neil Williams <linux at codehelp.co.uk>
+ * Copyright 2007 Joshua Sled <jsled at asynchronous.org>
+ */
+
/*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -23,13 +22,50 @@
* 02110-1301, USA
*/
-/** @addtogroup Trace
- @{ */
+/**
+ * @addtogroup Logging
+ * @{
+ * @ingroup QOF
+ * @brief Logging and tracing facility.
+ * @sa "Logging overhaul" announcement <http://lists.gnucash.org/pipermail/gnucash-devel/2007-February/019836.html>
+ *
+ * qof_log_init(void) installs a handler that interprets the "log_domain"
+ * as a "."-separated path. Log level thresholds can be set for each level
+ * in the tree. When a message is logged, the longest level match is
+ * found, and used as the threshold.
+ *
+ * For instance, we can set the levels as such:
+ * @verbatim
+ "qof" = WARN
+ "gnc" = WARN
+ "gnc.ui" = INFO
+ "gnc.ui.plugin-page.sx-list" = DEBUG
+ @endverbatim
+ *
+ * When code in the log_module of "gnc.import" attempts to log at DEBUG
+ * (let's say), the handler will attempt to match the log domain to
+ * successively-longer paths: first "", then "gnc", then "gnc.import". Given
+ * the settings above, the path "gnc" will match -- at a level of "WARN" --
+ * and the DEBUG-level log will be rejected. When code in the log domain of
+ * "gnc.ui.plugin-page.sx-list" logs at DEBUG, however, it will match at
+ * DEBUG, and be allowed.
+ *
+ * The current log format is as above:
+ *
+ * @verbatim
+ * [timestamp] [level] <[log-domain]> [message]
+ @endverbatim
+ *
+ * The timestamp and level are constant width (level is 5 characters). The
+ * log domain is re-iterated, which gives some context, but could become
+ * annoying if they get long.
+ *
+ * Trailing newlines (e.g. <tt>PINFO("...\n", ...)</tt>) are removed; the logger
+ * will newline separate output.
+ *
+ * @see qof_log_parse_log_config(const char*)
+ **/
-/** @file qoflog.h
- * @brief QOF error logging and tracing facility
-*/
-
#ifndef _QOF_LOG_H
#define _QOF_LOG_H
@@ -52,11 +88,11 @@
gchar* qof_log_level_to_string(QofLogLevel lvl);
QofLogLevel qof_log_level_from_string(gchar *str);
-/** indents once for each ENTER macro **/
+/** Indents one level; see ENTER macro. **/
void qof_log_indent(void);
/**
- * drops back one indent for each LEAVE macro, capped at 0.
+ * De-dent one level, capped at 0; see LEAVE macro.
**/
void qof_log_dedent(void);
@@ -66,38 +102,34 @@
**/
void qof_log_init (void);
-/**
- * Set the logging level of the given log_module.
- **/
+/** Set the logging level of the given log_module. **/
void qof_log_set_level(QofLogModule module, QofLogLevel level);
-/**
- * Specify an alternate log output, to pipe or file.
- **/
+/** Specify an alternate log output, to pipe or file. **/
void qof_log_set_file (FILE *outfile);
-/**
- * Specify a filename for log output.
- **/
+/** Specify a filename for log output. **/
void qof_log_init_filename (const gchar* logfilename);
/**
- * If {@param log_to_filename} is "stderr" or "stdout" (exactly,
+ * If @a log_to_filename is "stderr" or "stdout" (exactly,
* case-insensitive), then those special files are used; otherwise, the
- * literal filename as given, as {@link qof_log_init_filename}.
+ * literal filename as given, as qof_log_init_filename(gchar*)
**/
void qof_log_init_filename_special(const char *log_to_filename);
-/** Parse a log-configuration file. A GKeyFile-format file of the schema::
- *
- * [levels]
- * # log.ger.path=level
- * gnc.engine.sx=debug
- * gnc.gui.sx=debug
- * gnc.gui.freqspec=debug
- * [output]
- * # to=["stderr"|"stdout"|filename]
- * to=stderr
+/**
+ * Parse a log-configuration file. A GKeyFile-format file of the schema:
+ * @verbatim
+ [levels]
+ # log.ger.path=level
+ gnc.engine.sx=debug
+ gnc.gui.sx=debug
+ gnc.gui.freqspec=debug
+ [output]
+ # to=["stderr"|"stdout"|filename]
+ to=stderr
+ @endverbatim
**/
void qof_log_parse_log_config(const char *filename);
@@ -105,21 +137,19 @@
void qof_log_shutdown (void);
/**
- * qof_log_prettify() cleans up subroutine names. AIX/xlC has the habit
- * of printing signatures not names; clean this up. On other operating
- * systems, truncate name to QOF_LOG_MAX_CHARS chars.
+ * Cleans up subroutine names. AIX/xlC has the habit of printing signatures
+ * not names; clean this up. On other operating systems, truncate name to
+ * QOF_LOG_MAX_CHARS chars.
**/
const gchar * qof_log_prettify (const gchar *name);
-/** Do not log log_modules that have not been enabled. */
+/** Check to see if the given @a log_module is configured to log at the given
+ * @a log_level. This implements the "log.path.hierarchy" logic. **/
gboolean qof_log_check(QofLogModule log_module, QofLogLevel log_level);
-/** Set the default QOF log_modules to the log level. */
+/** Set the default level for QOF-related log paths. **/
void qof_log_set_default(QofLogLevel log_level);
-typedef void (*QofLogCB) (QofLogModule log_module, QofLogLevel* log_level,
- gpointer user_data);
-
#define PRETTY_FUNC_NAME qof_log_prettify(__FUNCTION__)
/** Log a fatal error */
@@ -162,17 +192,19 @@
} \
} while (0)
+/** Replacement for @c g_return_val_if_fail, but calls LEAVE if the test fails. **/
#define gnc_leave_return_val_if_fail(test, val) do { \
if (! (test)) { LEAVE(""); } \
g_return_val_if_fail(test, val); \
} while (0);
+/** Replacement for @c g_return_if_fail, but calls LEAVE if the test fails. **/
#define gnc_leave_return_if_fail(test) do { \
if (! (test)) { LEAVE(""); } \
g_return_if_fail(test); \
} while (0);
-/** Print a function exit debugging message */
+/** Print a function exit debugging message. **/
#define LEAVE(format, args...) do { \
if (qof_log_check(log_module, G_LOG_LEVEL_DEBUG)) { \
qof_log_dedent(); \
More information about the gnucash-changes
mailing list