su: updated documentation of debugging logs.

darcs-hash:20061009154955-65a35-a3904acd5038f0609a99c8bf8f703351e4c410cb.gz

libsofia-sip-ua/su/Doxyfile

@@ -7,6 +7,7 @@ INPUT 		     = su.docs sofia-sip .
 
 TAGFILES           += ../docs/msg.doxytags=../msg
 TAGFILES           += ../docs/sip.doxytags=../sip
+TAGFILES           += ../docs/docs.doxytags=..
 
 GENERATE_TAGFILE     = ../docs/su.doxytags
 

libsofia-sip-ua/su/sofia-sip/su_debug.h

@@ -31,20 +31,23 @@
  * @brief SU debugging macros
  *
  * The logging levels and macros to use are defined as follows:
- *  - su_log()      fatal errors, panic 
- *  - SU_DEBUG_0()  critical errors, minimal progress at subsystem level
- *  - SU_DEBUG_1()  non-critical errors
+ *  - SU_DEBUG_0()  fatal errors, panic 
+ *  - SU_DEBUG_1()  critical errors, minimal progress at subsystem level
+ *  - SU_DEBUG_2()  non-critical errors
  *  - SU_DEBUG_3()  warnings, progress messages
  *  - SU_DEBUG_5()  signaling protocol actions (incoming packets, etc.)
  *  - SU_DEBUG_7()  media protocol actions (incoming packets, etc.)
  *  - SU_DEBUG_9()  entering/exiting functions, very verbatim progress
  *
- * Module-specific logging requires redefining SU_LOG macro with a pointer
- * to a su_log_t variable.
+ * These macros are used to log with module-specific levels. The SU_LOG
+ * macro is redefined with a pointer to a module-specific #su_log_t
+ * structure, e.g., "iptsec_debug.h".
  *
  * @author Pekka Pessi <Pekka.Pessi@nokia.com>
  * 
  * @date Created: Tue Feb  8 10:06:33 2000 ppessi
+ *
+ * @sa @ref debug_logs, su_llog(), su_vllog(), #su_log_t, 
  */
 
 #ifndef SU_LOG_H
@@ -77,7 +80,12 @@ SOFIAPUBVAR su_log_t SU_LOG[];
     { va_list ap; va_start(ap, fmt); su_vllog(SU_LOG, level, fmt, ap); va_end(ap); }
 
 SU_DEBUG_DEF(0)
-/** Log critical errors, minimal progress at subsystem level. */
+/** Log messages at level 0.
+ *
+ * Fatal errors and panic messages should be logged at level 0. 
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_0(x) (SU_LOG_LEVEL >= 0 ? (su_debug_0 x) : (void)0)
 
 /** Log C library errors. */
@@ -93,7 +101,13 @@ SU_DEBUG_DEF(0)
 
 #if SU_DEBUG_MAX >= 1
 SU_DEBUG_DEF(1)
-/** Log non-critical errors. */
+/**Log messages at level 1.
+ *
+ * Critical errors and minimal progress at subsystem level should be logged
+ * at level 1.
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_1(x) (SU_LOG_LEVEL >= 1 ? (su_debug_1 x) : (void)0)
 #else
 #define SU_DEBUG_1(x) (void)1
@@ -101,7 +115,12 @@ SU_DEBUG_DEF(1)
 
 #if SU_DEBUG_MAX >= 2
 SU_DEBUG_DEF(2)
-/** Log messages at level 2. */
+/**Log messages at level 2. 
+ *
+ * Non-critical errors should be logged at level 2.
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_2(x) (SU_LOG_LEVEL >= 2 ? (su_debug_2 x) : (void)0)
 #else
 #define SU_DEBUG_2(x) (void)2
@@ -109,7 +128,12 @@ SU_DEBUG_DEF(2)
 
 #if SU_DEBUG_MAX >= 3
 SU_DEBUG_DEF(3)
-/** Log warnings, progress messages. */
+/** Log messages at level 3.
+ *
+ * Warnings and progress messages should be logged at level 3.
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_3(x) (SU_LOG_LEVEL >= 3 ? (su_debug_3 x) : (void)0)
 #else
 #define SU_DEBUG_3(x) (void)3
@@ -125,7 +149,13 @@ SU_DEBUG_DEF(4)
 
 #if SU_DEBUG_MAX >= 5
 SU_DEBUG_DEF(5)
-/** Log signaling protocol actions (incoming packets, etc.). */
+/** Log messages at level 5.
+ *
+ * Signaling protocol actions (incoming packets, etc.) should be logged
+ * at level 5.
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_5(x) (SU_LOG_LEVEL >= 5 ? (su_debug_5 x) : (void)0)
 #else
 #define SU_DEBUG_5(x) (void)5
@@ -141,7 +171,12 @@ SU_DEBUG_DEF(6)
 
 #if SU_DEBUG_MAX >= 7
 SU_DEBUG_DEF(7)
-/** Log media protocol actions (incoming packets, etc.). */
+/** Log messages at level 7.
+ *
+ * Media protocol actions (incoming packets, etc) should be logged at level 7. 
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_7(x) (SU_LOG_LEVEL >= 7 ? (su_debug_7 x) : (void)0)
 #else
 #define SU_DEBUG_7(x) (void)7
@@ -157,7 +192,13 @@ SU_DEBUG_DEF(8)
 
 #if SU_DEBUG_MAX >= 9
 SU_DEBUG_DEF(9)
-/** Log entering/exiting functions, very verbatim progress. */
+/** Log messages at level 9.
+ *
+ * Entering/exiting functions, very verbatim progress should be logged at
+ * level 9.
+ *
+ * @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
+ */
 #define SU_DEBUG_9(x) (SU_LOG_LEVEL >= 9 ? (su_debug_9 x) : (void)0)
 #else
 #define SU_DEBUG_9(x) (void)9

libsofia-sip-ua/su/sofia-sip/su_log.h

@@ -52,7 +52,7 @@ typedef struct su_log_s su_log_t;
 
 SOFIA_BEGIN_DECLS
 
-/**Prototype for logging function */
+/** Prototype for logging function */
 typedef void (su_logger_f)(void *stream, char const *fmt, va_list ap);
 
 /** Log object. */

libsofia-sip-ua/su/sofia-sip/su_osx_runloop.h

@@ -22,11 +22,12 @@
  *
  */
 
-#ifndef SU_OSX_RUNLOOP_H /** Defined when su_source.h has been included. */
+#ifndef SU_OSX_RUNLOOP_H
+/** Defined when <sofia-sip/su_osx_runloop.h> has been included. */
 #define SU_OSX_RUNLOOP_H
 
 /**
- * @file su_source.h
+ * @file sofia-sip/su_osx_runloop.h
  * @brief 
  * 
  * @author Martti Mela <Martti.Mela@nokia.com>
@@ -43,8 +44,8 @@
 
 SOFIA_BEGIN_DECLS
 
-su_root_t *su_root_osx_runloop_create(su_root_magic_t *) __attribute__((__malloc__));
-/* GSource *su_root_source(su_root_t *); */
+su_root_t *su_root_osx_runloop_create(su_root_magic_t *)
+  __attribute__((__malloc__));
 
 SOFIA_END_DECLS
 

libsofia-sip-ua/su/su.docs

@@ -99,15 +99,6 @@
  *    - #su_iovec_t: structure holding scatter-gather IO vector
  */
 
-/**@defgroup su_log Logging Interface
- *
- * Generic logging interface.
- *
- * The @b su_log submodule contains a generic logging interface. The
- * interface provides means for redirecting the log and filtering log
- * messages based on message priority.
- */
-
 /**@defgroup su_htable Hash tables
  *
  * Hash tables.

libsofia-sip-ua/su/su_log.c

@@ -54,11 +54,27 @@
 #define SU_LOG_UNLOCK(log)
 #endif
 
+/**@defgroup su_log Logging Interface
+ *
+ * Generic logging interface.
+ *
+ * The @b su_log submodule contains a generic logging interface. The
+ * interface provides means for redirecting the log and filtering log
+ * messages based on message priority.
+ *
+ * @sa @ref debug_logs, <sofia-sip/su_log.h>, 
+ * su_llog(), su_vllog(), #su_log_t, #SU_LOG,
+ * SU_DEBUG_0(), SU_DEBUG_1(), SU_DEBUG_2(), SU_DEBUG_3(), SU_DEBUG_5(), 
+ * SU_DEBUG_7(), SU_DEBUG_9()
+ */
+
+/** Log message of socket error @errcode at level 0. */
 void su_perror2(const char *s, int errcode)
 {
   su_log("%s: %s\n", s, su_strerror(errcode));
 }
 
+/** Log socket error message at level 0. */
 void su_perror(const char *s)
 {
   su_perror2(s, su_errno());

libsofia-sip-ua/su/su_osx_runloop.c

@@ -188,7 +188,7 @@ su_port_vtable_t const su_port_osx_vtable[1] =
 static int su_port_osx_wait_events(su_port_t *self, su_duration_t tout);
 
 
-/** 
+/* *
  * Port is a per-thread reactor.  
  *
  * Multiple root objects executed by single thread share a su_port_t object.