From ec7ef5322117129cf6f98ee891e7059af91e4e3b Mon Sep 17 00:00:00 2001
From: Yanbo Zhou <yanbo.zhou@intel.com>
Date: Fri, 30 Mar 2018 11:09:28 +0800
Subject: [PATCH] include/log.h: add comments for public APIs

Change-Id: I998ef4292e727afe5e97c7e48555cc6d7d4b3931
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/405830
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: GangCao <gang.cao@intel.com>
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
---
 include/spdk/log.h | 56 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/include/spdk/log.h b/include/spdk/log.h
index 6f8de562b..59eaa70a1 100644
--- a/include/spdk/log.h
+++ b/include/spdk/log.h
@@ -66,13 +66,17 @@ enum spdk_log_level {
 };
 
 /**
- * Set the threshold to log messages. Messages with a higher
+ * Set the log level threshold to log messages. Messages with a higher
  * level than this are ignored.
+ *
+ * \param level Log level threshold to set to log messages.
  */
 void spdk_log_set_level(enum spdk_log_level level);
 
 /**
- * Get the current log threshold.
+ * Get the current log level threshold.
+ *
+ * \return the current log level threshold.
  */
 enum spdk_log_level spdk_log_get_level(void);
 
@@ -80,11 +84,15 @@ enum spdk_log_level spdk_log_get_level(void);
  * Set the current log level threshold for printing to stderr.
  * Messages with a level less than or equal to this level
  * are also printed to stderr.
+ *
+ * \param level Log level threshold for printing to stderr.
  */
 void spdk_log_set_print_level(enum spdk_log_level level);
 
 /**
  * Get the current log level print threshold.
+ *
+ * \return the current log level print threshold.
  */
 enum spdk_log_level spdk_log_get_print_level(void);
 
@@ -95,15 +103,59 @@ enum spdk_log_level spdk_log_get_print_level(void);
 #define SPDK_ERRLOG(...) \
 	spdk_log(SPDK_LOG_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)
 
+/**
+ * Write messages to the log file.
+ *
+ * \param level Log level threshold.
+ * \param file Name of the current source file.
+ * \param line Current source line number.
+ * \param func Current source function name.
+ * \param format Format string to the message.
+ */
 void spdk_log(enum spdk_log_level level, const char *file, const int line, const char *func,
 	      const char *format, ...) __attribute__((__format__(__printf__, 5, 6)));
 
+/**
+ * Dump the trace to a file.
+ *
+ * \param fp File to hold the trace.
+ * \param label Label to print to the file.
+ * \param buf Buffer that holds the trace information.
+ * \param len Length of trace to dump.
+ */
 void spdk_trace_dump(FILE *fp, const char *label, const void *buf, size_t len);
 
+/**
+ * Check whether the trace flag exists and is enabled.
+ *
+ * \return true if enabled, or false otherwise.
+ */
 bool spdk_log_get_trace_flag(const char *flag);
+
+/**
+ * Enable the trace flag.
+ *
+ * \param flag Trace flag to be enabled.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_log_set_trace_flag(const char *flag);
+
+/**
+ * Clear a trace flag.
+ *
+ * \flag Trace flag to clear.
+ *
+ * \return 0 on success, -1 on failure.
+ */
 int spdk_log_clear_trace_flag(const char *flag);
 
+/**
+ * Show all the log trace flags and their usage.
+ *
+ * \param f File to hold all the flags' information.
+ * \param trace_arg Command line option to set/enable the trace flag.
+ */
 void spdk_tracelog_usage(FILE *f, const char *trace_arg);
 
 #ifdef __cplusplus