From 429b8acfd627e4cc863b4694545e30cf59ed4758 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= <noselasd@fiane.dyndns.org>
Date: Tue, 30 Oct 2012 18:44:58 +0100
Subject: [PATCH] Add documentation to ucore_logging.h

---
 src/ucore_logging.h | 89 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

diff --git a/src/ucore_logging.h b/src/ucore_logging.h
index 9173e4e..e3fea28 100644
--- a/src/ucore_logging.h
+++ b/src/ucore_logging.h
@@ -1,6 +1,7 @@
 #ifndef UCORE_LOGGING_H_
 #define UCORE_LOGGING_H_
 
+/** The log levels defined by ucore logging*/
 enum UC_LOG_LEVEL {
     UC_LL_NONE    = 0,
     UC_LL_DEBUG   = 1,
@@ -9,43 +10,124 @@ enum UC_LOG_LEVEL {
     UC_LL_ERROR   = 7,
 };
 
+/** A destination for the logging messages*/
 enum UC_LOG_DESTINATION {
+    /** Logs using the unix syslog system */
     UC_LDEST_SYSLOG,
+
+    /** Prints log messages to stderr. */
     UC_LDEST_STDERR,
+
+    /** Prints log messages to a file */
     UC_LDEST_FILE,
 };
 
+/** A module of a program, that will perform logging.
+ * This is used group logging from parts of a larger program,
+ * and allow the log message to identigy which module the
+ * log message originates from
+ */
 struct uc_log_module {
+    /** The id of the log module.
+     * This is the id one specifies in the various log
+     * functions/macros*/
     int id;
+
+    /** A short name for the module.
+     * This will appear in log messages */
     const char *short_name;
+    /** A longer description for the log module*/
     const char *long_name;
+    /** The log level of this module. Only
+     * log statements with a level >= the log_level
+     * are actually logged */
     int log_level;
 };
 
+/* A collection of struct uc_log_module */
 struct uc_log_modules {
+    /* Pointer to the first element of the array */
     struct uc_log_module *mods;
+    /** The number of elements in the mods array. */
     int cnt;
 };
 
 struct uc_log_destination;
 
 
+/* Returns a string representation of the log level.
+ *
+ * @ll The log level
+ * @return String representation of the log level. (This will be a string literal)
+ */
 const char *uc_ll_2_str(enum UC_LOG_LEVEL l);
 
+/* creates a new uc_log_destination for printing on stderr.
+ *
+ * @log_level log level of this destination. only log messages
+ * with a log level >= the log level of the destination are actually logged.
+ * @log_location whether to log info about the source file and line number
+ * in a log message.
+ *
+ * @return An opaque uc_log_destination that can be added as a destination to
+ * the ucore logging system
+ */
 struct uc_log_destination *uc_log_new_stderr(int log_level, int log_location);
 
+/* creates a new uc_log_destination for logging to syslog
+ *
+ * @ident The ident as used in the syslog openlog() funcion
+ * @facility The facility as used in the syslog openlog() function()
+ * @log_level log level of this destination. only log messages
+ * with a log level >= the log level of the destination are actually logged.
+ * @log_location whether to log info about the source file and line number
+ * in a log message.
+ * @return An opaque uc_log_destination that can be added as a destination to
+ * the ucore logging system
+ */
 struct uc_log_destination *uc_log_new_syslog(const char *ident, int facility, int log_level, int log_location);
 
+/* creates a new uc_log_destination for printing on stderr.
+ *
+ * @log_level log level of this destination. only log messages
+ * with a log level >= the log level of the destination are actually logged.
+ * @log_location whether to log info about the source file and line number
+ * in a log message.
+ * @return An opaque uc_log_destination that can be added as a destination to
+ * the ucore logging system
+ */
 struct uc_log_destination *uc_log_new_file(const char *filename, int log_level, int log_location);
 
+ /** Add a uc_log_destination to the logging system.
+  *
+  * @dest The uc_log_destination to add.
+  */
 void uc_log_add_destination(struct uc_log_destination *dest);
 
+/** Remove a log destination.
+ *
+ * @dest The uc_log_destination to remove.
+ */
 void uc_log_remove_destination(struct uc_log_destination *dest);
 
+/** Change the log level of a module.
+ *
+ * @module The module to change, matched against the id member of a struct uc_log_module
+ */
 int uc_log_module_set_loglevel(int module, enum UC_LOG_LEVEL level);
 
+/** Closes and re-opens all the UC_LDEST_FILE log destinations.
+ * Intended for use when a log file is rotated externally.
+ *
+ * @return 0 on success, non-zero if an error occured when re-opening a file.
+ */
 int uc_log_reopen_files(void);
 
+/** Init the logging system. This function must be called before performing any other
+ * logging action.
+ *
+ * @user_struct containing an array of all the modules defined by the application.
+ */
 void uc_log_init(struct uc_log_modules *user_modules);
 
 void uc_logf(int log_level, int module, const char *file, int line, const char *fmt, ...) __attribute__((format(printf, 5, 6)));
@@ -56,6 +138,13 @@ void uc_logf(int log_level, int module, const char *file, int line, const char *
 #   define UC_DEBUGF(mod, fmt, ...)
 #endif
 
+/** Main macro that should be used for logging.
+ *
+ * @lvl log level of this log message
+ * @mod module id of this log messagex.
+ * @fmt printf style format string
+ * @... printf style arguments
+ */
 #define UC_LOGF(lvl, mod, fmt, ...) uc_logf(lvl, mod, __FILE__, __LINE__, fmt, ## __VA_ARGS__)
 
 #endif