Pass through indent and add more doxygen comments.

shared/report.c

@@ -3,7 +3,6 @@
  */
 
 /*-
- * report.c
  * This file is part of LCDproc.
  *
  * This file is released under the GNU General Public License. Refer to the
@@ -31,24 +30,24 @@ static char *stored_msgs[MAX_STORED_MSGS];
 static int stored_levels[MAX_STORED_MSGS];
 static int num_stored_msgs = 0;
 
-
 /* local functions */
 static void store_report_message(int level, const char *message);
 static void flush_messages();
 
-void report( const int level, const char *format, .../*args*/ )
+void
+report(const int level, const char *format,... /* args */ )
 {
 	/* Check if we should report it */
 	if (level <= report_level || report_dest == RPT_DEST_STORE) {
-
 		char buf[1024];
 
-		/* Following functions appear to work on RedHat and Debian
+		/*
+		 * Following functions appear to work on RedHat and Debian
 		 * Linux, FreeBSD and Solaris
 		 */
 
 		va_list ap;
-		va_start(ap, format); /* measure the required size (the number of elements of format) */
+		va_start(ap, format);
 
 		switch (report_dest) {
 		    case RPT_DEST_STDERR:
@@ -60,7 +59,7 @@ void report( const int level, const char *format, .../*args*/ )
 			break;
 		    case RPT_DEST_STORE:
 			vsnprintf(buf, sizeof(buf), format, ap);
-			buf[sizeof(buf)-1] = 0; /* be sure to have a terminating 0 */
+			buf[sizeof(buf) - 1] = 0;
 			store_report_message(level, buf);
 			break;
 		}
@@ -69,7 +68,8 @@ void report( const int level, const char *format, .../*args*/ )
 }
 
 
-int set_reporting( char *application_name, int new_level, int new_dest )
+int
+set_reporting(char *application_name, int new_level, int new_dest)
 {
 	if (new_level < RPT_CRIT || new_level > RPT_DEBUG) {
 		report(RPT_ERR, "report level invalid: %d", new_level);
@@ -86,6 +86,10 @@ int set_reporting( char *application_name, int new_level, int new_dest )
 	report_level = new_level;
 	report_dest = new_dest;
 
+	/*
+	 * Flush all messages currently in the message store if the new
+	 * destination is not the store itself.
+	 */
 	if (report_dest != RPT_DEST_STORE)
 		flush_messages();
 
@@ -93,7 +97,12 @@ int set_reporting( char *application_name, int new_level, int new_dest )
 }
 
 
-static void store_report_message( int level, const char *message )
+/**
+ * Puts a message into the message store. If the store is full new messages
+ * are silently discarded.
+ */
+static void
+store_report_message(int level, const char *message)
 {
 	if (num_stored_msgs < MAX_STORED_MSGS) {
 		stored_msgs[num_stored_msgs] = malloc(strlen(message) + 1);
@@ -104,7 +113,12 @@ static void store_report_message( int level, const char *message )
 }
 
 
-static void flush_messages()
+/**
+ * Report all messages contained in the message store to the current report
+ * destination and release their memory.
+ */
+static void
+flush_messages()
 {
 	int i;
 	for (i = 0; i < num_stored_msgs; i++) {

shared/report.h

@@ -1,9 +1,24 @@
 /** \file shared/report.h
  * Contains reporting functions.
+ *\verbatim
+ *
+ * To enable the debug() function on all of the software, just type:
+ * ./configure --enable-debug
+ * and recompile with 'make'
+ *
+ * To enable the debug() function only in specific files:
+ * 1) Configure without enabling debug (that is without --enable-debug)
+ * 2) Edit the source file that you want to debug and put the following
+ *    line at the top, before the #include "report.h" line:
+ *    #define DEBUG
+ * 3) Then recompile with 'make'
+ *
+ * This way, the global DEBUG macro is off but is locally enabled in
+ * certains parts of the software.
+ *\endverbatim
  */
 
 /*-
- * report.h
  * This file is part of LCDd, the lcdproc server.
  *
  * This file is released under the GNU General Public License. Refer to the
@@ -17,89 +32,72 @@
 #ifndef REPORT_H
 #define REPORT_H
 
-/** DEBUGGING / REPORTING
- *\verbatim
- *
- * To enable the debug() function on all of the software, just type:
- * ./configure --enable-debug
- * and recompile with 'make'
- *
- * To enable the debug() function only in specific files:
- * 1) Configure without enabling debug (that is without --enable-debug)
- * 2) Edit the source file that you want to debug and put the following
- *    line at the top, before the #include "report.h" line:
- *    #define DEBUG
- * 3) Then recompile with 'make'
- * This way, the global DEBUG macro is off but is locally enabled in
- * certains parts of the software.
- *
- * The reporting levels have the following meaning:
- *
- *   0 RPT_CRIT		Critical conditions: the program stops right after
- *			this. Only use this if the program is actually exited
- *			from the current function.
- *   1 RPT_ERR		Error conditions: serious problem, program continues.
- * 			Use this just before you return -1 from a function.
- *   2 RPT_WARNING	Warning conditions: Something that the user should
- *			fix, but the program can continue without a real
- *			problem.
- *			Ex: Protocol errors from a client.
- *   3 RPT_NOTICE	Major event in the program.
- *			Ex: (un)loading of driver, client (dis)connect.
- *   4 RPT_INFO		Minor event in the program: the activation of a
- *			setting, details of a loaded driver, a key
- *			reservation, a keypress, a screen switch.
- *   5 RPT_DEBUG	Insignificant event.
- *			Ex: What function has been called, what subpart of a
- *			function is being executed, what was received and sent
- *			over the socket, etc.
- *
- * Levels 4 (maybe) and 5 (certainly) should be reported using the debug
- * function.
- * The code that this function generates will not be in the executable when
- * compiled without debugging. This way memory and CPU cycles are saved.
- *\endverbatim
- */
-
-#ifdef HAVE_CONFIG_H
-# include "config.h"
-#endif
-
 #include <stdarg.h>
 #include <stdio.h>
 
-
 /* Reporting levels */
+/**
+ * \def RPT_CRIT
+ *	Critical conditions: the program stops right after this.
+ *	Only use this if the program is actually exited from the current
+ *	function.
+ *
+ * \def RPT_ERR
+ *	Error conditions: serious problem, program continues.
+ *	Use this just before you return -1 from a function.
+ *
+ * \def RPT_WARNING
+ *	Warning conditions: Something that the user should Fix, but the
+ *	program can continue without a real problem.
+ *	Ex: Protocol errors from a client.
+ *
+ * \def RPT_NOTICE
+ *	Major event in the program.
+ *	Ex: (un)loading of driver, client (dis)connect.
+ *
+ * \def RPT_INFO
+ *	Minor event in the program: the activation of a Setting, details of a
+ *	loaded driver, a key reservation, a keypress, a screen switch.
+ *
+ * \def RPT_DEBUG
+ *	Insignificant event.
+ *	Ex: What function has been called, what subpart of a function is being
+ *	executed, what was received and sent over the socket, etc.
+ */
 #define RPT_CRIT 0
 #define RPT_ERR 1
 #define RPT_WARNING 2
 #define RPT_NOTICE 3
 #define RPT_INFO 4
 #define RPT_DEBUG 5
-/* Don't just modify these numbers, they're related to syslog. */
+/* Don't modify these numbers, they're related to syslog! */
 
 /* Reporting destinations */
 #define RPT_DEST_STDERR 0
 #define RPT_DEST_SYSLOG 1
 #define RPT_DEST_STORE 2
 
+/** Sets reporting level and message destination. */
 int set_reporting( char *application_name, int new_level, int new_dest );
-/* Sets reporting level and message destination. */
 
+/** Report the message to the selected destination if important enough */
 void report( const int level, const char *format, .../*args*/ );
-/* Report the message to the selected destination if important enough */
 
-/* Consider the debug function to be exactly the same as the report function.
+/**
+ * The code that this function generates will not be in the executable when
+ * compiled without debugging. This way memory and CPU cycles are saved.
+ */
+static inline void dont_report( const int level, const char *format, .../*args*/ )
+{}
+
+/**
+ * Consider the debug function to be exactly the same as the report function.
  * The only difference is that it is only compiled in if DEBUG is defined.
  */
-
-static inline void dont_report( const int level, const char *format, .../*args*/ )
-{} /* The idea is that this gets optimized out */
-
 #ifdef DEBUG
 #  define debug report
 #else
 #  define debug dont_report
-#endif /*DEBUG*/
-
 #endif
+
+#endif  /* REPORT_H */