Adding more comments

src/include/drv/rts-logger.h

@@ -42,29 +42,67 @@ enum RTSLOG_LOG_LEVEL
 // Start user functions
 //
 
+/**
+ * @usage This is the main interface that should be used to log messages
+ *        from front end code infrastructure. The default log level is INFO,
+ *        so you must set the logger level to DEBUG before you will see debug
+ *        level messages. 
+ *
+ * These macros can be used just like prink or printf:
+ *
+ * RTSLOG_INFO("A string: %s and an int: %d\n", "Hello", 5);
+ *
+ */
 #define RTSLOG_RAW(fmt, ...) rtslog_print(RTSLOG_LOG_LEVEL_RAW, fmt, ##__VA_ARGS__)
 #define RTSLOG_DEBUG(fmt, ...) rtslog_print (RTSLOG_LOG_LEVEL_DEBUG, RTS_LOG_PREFIX ": DEBUG - " fmt, ##__VA_ARGS__)
 #define RTSLOG_INFO(fmt, ...) rtslog_print (RTSLOG_LOG_LEVEL_INFO, RTS_LOG_PREFIX ": INFO - " fmt, ##__VA_ARGS__)
 #define RTSLOG_WARN(fmt, ...) rtslog_print (RTSLOG_LOG_LEVEL_WARN, RTS_LOG_PREFIX ": WARN - " fmt, ##__VA_ARGS__)
 #define RTSLOG_ERROR(fmt, ...) rtslog_print (RTSLOG_LOG_LEVEL_ERROR, RTS_LOG_PREFIX ": ERROR - " fmt, ##__VA_ARGS__)
 
-int rtslog_set_log_level(int new_level);
-int rtslog_get_log_level( void );
-int rtslog_get_num_dropped_space ( void );
-int rtslog_get_num_ready_to_print( void );
-
-
-
-
-
-
-
-
 
+//
+// Debugging/Stats functions
+//
 
+/**
+* @brief Requests the new log level be set in the logger.
+* 
+* When the kernel module version is being used the sysfs interface
+* can be used to set this value. 
+*
+* cat /sys/kernel/rts_logger/debug_level
+*
+* @param new_level  The new log level to set (a RTSLOG_LOG_LEVEL)
+*
+* @return 1 if the log level was set, 0 if the log level was invalid        
+*/
+int rtslog_set_log_level(int new_level);
 
+/**
+* @brief Requests the new log level be set in the logger
+*
+* @return The level set (a RTSLOG_LOG_LEVEL)
+*/
+int rtslog_get_log_level( void );
 
+/**
+* @brief Requests number of messages that have been dropped
+*        due to a full buffer. This should't happen, but can
+*        if too many modules are spamming messages faster than
+*        they can be printed. This is an accumulative count 
+*        from module insertion (kernel space), or process creation (usermode)
+*
+* @return The number of messages that have been dropped 
+*/
+int rtslog_get_num_dropped_space ( void );
 
+/**
+* @brief Requests number of messages that are currently 
+*        queued, waiting for printing.
+*
+* @return The number of messages that are queued for print
+*/
+int rtslog_get_num_ready_to_print( void );
 
 
 
@@ -79,7 +117,20 @@ int rtslog_get_num_ready_to_print( void );
 //
 // Internal functions
 //
+
+/**
+* @brief Don't call this function directly, use the macros above
+*
+* Passes the message to the logger for logging
+*
+* @param level The log level of this message
+* @param fmt   The format string of the message
+* @param ...   Arguments for the format string
+*
+* @return none
+*/
+
 void rtslog_print(int level, const char * fmt, ...);
 
 
-#endif
+#endif //LIGO_RTS_LOGGER_H_INCLUDED