From f25f831093913b47ecc57c9e089f81b6ab1db602 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= <noselasd@fiane.dyndns.org>
Date: Tue, 6 Nov 2012 19:04:17 +0100
Subject: [PATCH] Add some high level docs in ucore_logging.h

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

diff --git a/src/ucore_logging.h b/src/ucore_logging.h
index 5f19efb..f3c9cfe 100644
--- a/src/ucore_logging.h
+++ b/src/ucore_logging.h
@@ -5,6 +5,59 @@
  * All logging functions except uc_log_init are thread safe,
  * so logging can be performed from any thread after the logging 
  * system have been initialized.
+ *
+ * The logging system has the concept of 'modules'. Modules are defined
+ * by the application, and would match the logical parts of an application.
+ * uc_log_init() tells the logging library about these modules, and would normally
+ * be used like:
+ *
+ * enum {
+ *      POLLER,
+ *      DB,
+ *      IO
+ *};
+ *
+ * struct uc_log_module modules[] = {
+ *      {
+ *          .id = POLLER,
+ *          .short_name = "POLLER",
+ *          .long_name = "Poller thread",
+ *          .log_level = UC_LL_DEBUG,
+ *      },
+ *      {
+ *          .id = DB,
+ *          .short_name = "DB",
+ *          .long_name = "Database handler",
+ *          .log_level == UC_LL_DEBUG
+ *      },
+ *      {
+ *          .id = IO,
+ *          .short_name = "IO",
+ *          .long_name = "I/O worker",
+ *          .log_level == UC_LL_DEBUG
+ *      }
+ * };
+ * struct uc_log_modules m = {
+ *      .mods = modules,
+ *      .cnt = ARRAY_SIZE(modules)
+ *  };
+ *
+ *  uc_log_init(&m);
+ *
+ *  So the application defines 3 modules logging
+ *  will be categorized by.
+ *  Note that the values (the enum in this case) 
+ *  defining all the .id memmbers of uc_log_module
+ *  must start at 0 and be concecutive.
+ *
+ *  Now, the database code in the application can do
+ *  logging as e.g.
+ *
+ *    UC_LOGF(UC_LL_INFO, DB, "connecting to server %s\n", ip);
+ *
+ *  And the resulting log line will include the short_name
+ *  modules[DB].short_name
+ *
  */
 
 /** The log levels defined by ucore logging*/