doxygen documentation for logging framework

1 files changed, 44 insertions, 25 deletions

diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index 537dc609..94762118 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -1,10 +1,12 @@
 #ifndef _OSMOCORE_LOGGING_H
 #define _OSMOCORE_LOGGING_H
 
-/*! \file logging.h
- *  \brief Osmocom logging framework
+/*! \defgroup logging Osmocom logging framework
+ *  @{
  */
 
+/*! \file logging.h */
+
 #include <stdio.h>
 #include <stdint.h>
 #include <osmocom/core/linuxlist.h>
@@ -45,12 +47,12 @@ void logp(int subsys, char *file, int line, int cont, const char *format, ...) _
 #define LOGPC(ss, level, fmt, args...) \
 	logp2(ss, level, __FILE__, __LINE__, 1, fmt, ##args)
 
-/* different levels */
-#define LOGL_DEBUG	1	/* debugging information */
+/*! \brief different log levels */
+#define LOGL_DEBUG	1	/*!< \brief debugging information */
 #define LOGL_INFO	3
-#define LOGL_NOTICE	5	/* abnormal/unexpected condition */
-#define LOGL_ERROR	7	/* error condition, requires user action */
-#define LOGL_FATAL	8	/* fatal, program aborted */
+#define LOGL_NOTICE	5	/*!< \brief abnormal/unexpected condition */
+#define LOGL_ERROR	7	/*!< \brief error condition, requires user action */
+#define LOGL_FATAL	8	/*!< \brief fatal, program aborted */
 
 #define LOG_FILTER_ALL	0x0001
 
@@ -68,53 +70,67 @@ struct log_category {
 	uint8_t enabled;
 };
 
+/*! \brief Information regarding one logging category */
 struct log_info_cat {
-	const char *name;
-	const char *color;
-	const char *description;
-	uint8_t loglevel;
-	uint8_t enabled;
+	const char *name;		/*!< name of category */
+	const char *color;		/*!< color string for cateyory */
+	const char *description;	/*!< description text */
+	uint8_t loglevel;		/*!< currently selected log-level */
+	uint8_t enabled;		/*!< is this category enabled or not */
 };
 
-/* log context information, passed to filter */
+/*! \brief Log context information, passed to filter */
 struct log_context {
 	void *ctx[LOG_MAX_CTX+1];
 };
 
 struct log_target;
 
+/*! \brief Log filter function */
 typedef int log_filter(const struct log_context *ctx,
 		       struct log_target *target);
 
+/*! \brief Logging configuration, passed to \ref log_init */
 struct log_info {
-	/* filter callback function */
+	/* \brief filter callback function */
 	log_filter *filter_fn;
 
-	/* per-category information */
+	/*! \brief per-category information */
 	struct log_info_cat *cat;
+	/*! \brief total number of categories */
 	unsigned int num_cat;
+	/*! \brief total number of user categories (not library) */
 	unsigned int num_cat_user;
 };
 
+/*! \brief Type of logging target */
 enum log_target_type {
-	LOG_TGT_TYPE_VTY,
-	LOG_TGT_TYPE_SYSLOG,
-	LOG_TGT_TYPE_FILE,
-	LOG_TGT_TYPE_STDERR,
+	LOG_TGT_TYPE_VTY,	/*!< \brief VTY logging */
+	LOG_TGT_TYPE_SYSLOG,	/*!< \brief syslog based logging */
+	LOG_TGT_TYPE_FILE,	/*!< \brief text file logging */
+	LOG_TGT_TYPE_STDERR,	/*!< \brief stderr logging */
 };
 
+/*! \brief structure representing a logging target */
 struct log_target {
-        struct llist_head entry;
+        struct llist_head entry;		/*!< \brief linked list */
 
+	/*! \brief Internal data for filtering */
 	int filter_map;
+	/*! \brief Internal data for filtering */
 	void *filter_data[LOG_MAX_FILTERS+1];
 
+	/*! \brief logging categories */
 	struct log_category *categories;
 
+	/*! \brief global log level */
 	uint8_t loglevel;
+	/*! \brief should color be used when printing log messages? */
 	unsigned int use_color:1;
+	/*! \brief should log messages be prefixed with a timestamp? */
 	unsigned int print_timestamp:1;
 
+	/*! \brief the type of this log taget */
 	enum log_target_type type;
 
 	union {
@@ -133,6 +149,12 @@ struct log_target {
 		} tgt_vty;
 	};
 
+	/*! \brief call-back function to be called when the logging framework
+	 *	   wants to log somethnig.
+	 *  \param[[in] target logging target
+	 *  \param[in] level log level of currnet message
+	 *  \param[in] string the string that is to be written to the log
+	 */
         void (*output) (struct log_target *target, unsigned int level,
 			const char *string);
 };
@@ -169,12 +191,7 @@ struct log_target *log_target_create_syslog(const char *ident, int option,
 					    int facility);
 int log_target_file_reopen(struct log_target *tgt);
 
-/*! \brief Add a new logging target
- */
 void log_add_target(struct log_target *target);
-
-/*! \brief Deelete an existing logging target
- */
 void log_del_target(struct log_target *target);
 
 /* Generate command string for VTY use */
@@ -184,4 +201,6 @@ const char *log_vty_command_description(const struct log_info *info);
 struct log_target *log_target_find(int type, const char *fname);
 extern struct llist_head osmo_log_target_list;
 
+/*! }@ */
+
 #endif /* _OSMOCORE_LOGGING_H */