Changeset e0c836e8 in mainline for uspace/lib/c/generic/io

Timestamp:

2012-09-07T08:29:43Z (13 years ago)

Author:

Vojtech Horky <vojtechhorky@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

42bde6a

Parents:

70253688

Message:

Add comments to logging interface in libc

Location:

uspace/lib/c/generic/io

Files:

• log.c (modified) (8 diffs)
• logctl.c (modified) (2 diffs)

uspace/lib/c/generic/io/log.c

@@ -43 +43 @@
 #include <ns.h>
 
+/** Id of the first log we create at logger. */
 static sysarg_t default_log_id;
 
@@ -48 +49 @@
 static const char *log_prog_name;
 
+/** Names of individual log levels. */
 static const char *log_level_names[] = {
         "fatal",
@@ -64 +66 @@
 #define MESSAGE_BUFFER_SIZE 4096
 
+/** Send formatted message to the logger service.
+ *
+ * @param session Initialized IPC session with the logger.
+ * @param log Log to use.
+ * @param level Verbosity level of the message.
+ * @param message The actual message.
+ * @return Error code of the conversion or EOK on success.
+ */
 static int logger_message(async_sess_t *session, log_t log, log_level_t level, char *message)
 {
@@ -98 +108 @@
 }
 
+/** Get name of the log level.
+ *
+ * @param level The log level.
+ * @return String name or "unknown".
+ */
 const char *log_level_str(log_level_t level)
 {
@@ -106 +121 @@
 }
 
+/** Convert log level name to the enum.
+ *
+ * @param[in] name Log level name or log level number.
+ * @param[out] level_out Where to store the result (set to NULL to ignore).
+ * @return Error code of the conversion or EOK on success.
+ */
 int log_level_from_str(const char *name, log_level_t *level_out)
 {
@@ -137 +158 @@
 /** Initialize the logging system.
  *
- * @param prog_name     Program name, will be printed as part of message
+ * @param prog_name Program name, will be printed as part of message
  */
 int log_init(const char *prog_name)
@@ -190 +211 @@
 /** Write an entry to the log.
  *
- * @param level         Message verbosity level. Message is only printed
- *                      if verbosity is less than or equal to current
- *                      reporting level.
- * @param fmt           Format string (no traling newline).
+ * The message is printed only if the verbosity level is less than or
+ * equal to currently set reporting level of the log.
+ *
+ * @param ctx Log to use (use LOG_DEFAULT if you have no idea what it means).
+ * @param level Severity level of the message.
+ * @param fmt Format string in printf-like format (without trailing newline).
  */
 void log_msg(log_t ctx, log_level_t level, const char *fmt, ...)
@@ -206 +229 @@
 /** Write an entry to the log (va_list variant).
  *
- * @param level         Message verbosity level. Message is only printed
- *                      if verbosity is less than or equal to current
- *                      reporting level.
- * @param fmt           Format string (no trailing newline)
+ * @param ctx Log to use (use LOG_DEFAULT if you have no idea what it means).
+ * @param level Severity level of the message.
+ * @param fmt Format string in printf-like format (without trailing newline).
+ * @param args Arguments.
  */
 void log_msgv(log_t ctx, log_level_t level, const char *fmt, va_list args)

uspace/lib/c/generic/io/logctl.c

@@ -65 +65 @@
 }
 
-
+/** Set default reported log level (global setting).
+ *
+ * This setting affects all logger clients whose reporting level was
+ * not yet changed.
+ *
+ * If logging level of client A is changed with logctl_set_log_level()
+ * to some level, this call will have no effect at that client's reporting
+ * level. Even if the actual value of the reporting level of client A is
+ * the same as current (previous) default log level.
+ *
+ * @param new_level New reported logging level.
+ * @return Error code of the conversion or EOK on success.
+ */
 int logctl_set_default_level(log_level_t new_level)
 {
@@ -81 +93 @@
 }
 
+/** Set reported log level of a single log.
+ *
+ * @see logctl_set_default_level
+ *
+ * @param logname Log name.
+ * @param new_level New reported logging level.
+ * @return Error code of the conversion or EOK on success.
+ */
 int logctl_set_log_level(const char *logname, log_level_t new_level)
 {