Initial doxygen documentation for rc.h and einfo.h. Plus some header clean ups.

1 files changed, 88 insertions, 41 deletions

diff --git a/src/einfo.h b/src/einfo.h
index dc07b903..94c99072 100644
--- a/src/einfo.h
+++ b/src/einfo.h
@@ -1,21 +1,31 @@
-/*
-   rc.h 
-   Header file for external applications to get RC information.
-   Copyright 2007 Gentoo Foundation
-   Released under the GPLv2
-   */
+/*!
+ * @file einfo.h 
+ * @brief Describes how to interface with the einfo library
+ *
+ * Copyright 2007 Gentoo Foundation
+ * Released under the GPLv2
+ */
 
 #ifndef __EINFO_H__
 #define __EINFO_H__
 
+#define EINFO_PRINTF
+#define EINFO_XPRINTF
+#define EEND_PRINTF
+
 #ifdef __GNUC__
-#  define EINFO_PRINTF(_one, _two)  __attribute__ ((__format__ (__printf__, _one, _two)))
-#  define EINFO_XPRINTF(_one, _two)  __attribute__ ((__noreturn__, __format__ (__printf__, _one, _two)))
+#  undef EINFO_PRINTF
+#  undef EINFO_XPRINTF
+#  undef EEND_PRINTF
+#  define EINFO_PRINTF  __attribute__ ((__format__ (__printf__, 1, 2)))
+#  define EINFO_XPRINTF  __attribute__ ((__noreturn__, __format__ (__printf__, 1, 2)))
+#  define EEND_PRINTF  __attribute__ ((__format__ (__printf__, 2, 3)))
 #endif
 
 #include <sys/types.h>
 #include <stdbool.h>
 
+/*! @brief Color types to use */
 typedef enum
 {
 	ecolor_good,
@@ -26,46 +36,83 @@ typedef enum
 	ecolor_normal
 } einfo_color_t;
 
-/* We work out if the terminal supports colour or not through the use
-   of the TERM env var. We cache the reslt in a static bool, so
-   subsequent calls are very fast.
-   The n suffix means that a newline is NOT appended to the string
-   The v suffix means that we only print it when RC_VERBOSE=yes
-   NOTE We use the v suffix here so we can add veinfo for va_list
-   in the future, but veinfo is used by shell scripts as they don't
-   have the va_list concept
-   */
+/*! @brief Returns the ASCII code for the color */
 const char *ecolor (einfo_color_t);
-void elog (int level, const char *fmt, ...) EINFO_PRINTF (2, 3);
-int einfon (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int ewarnn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int eerrorn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int einfo (const char *fmt, ...) EINFO_PRINTF(1, 2);
-int ewarn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-void ewarnx (const char *fmt, ...) EINFO_XPRINTF (1,2);
-int eerror (const char *fmt, ...) EINFO_PRINTF (1,2);
-void eerrorx (const char *fmt, ...) EINFO_XPRINTF (1,2);
-int ebegin (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int eend (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
-int ewend (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
+
+/*! @brief Writes to syslog. */
+void elog (int level, const char *fmt, ...) EEND_PRINTF;
+
+/*!
+ * @brief Display informational messages.
+ *
+ * The einfo family of functions display messages in a consistent manner
+ * across Gentoo applications. Basically they prefix the message with
+ * " * ". If the terminal can handle color then we color the * based on
+ * the command used. Otherwise we are identical to the printf function.
+ *
+ * - einfo  - green
+ * - ewarn  - yellow
+ * - eerror - red
+ *
+ * The n suffix denotes that no new line should be printed.
+ * The v suffix means only print if RC_VERBOSE is yes.
+ */
+/*@{*/
+int einfon (const char *fmt, ...) EINFO_PRINTF;
+int ewarnn (const char *fmt, ...) EINFO_PRINTF;
+int eerrorn (const char *fmt, ...) EINFO_PRINTF;
+int einfo (const char *fmt, ...) EINFO_PRINTF;
+int ewarn (const char *fmt, ...) EINFO_PRINTF;
+void ewarnx (const char *fmt, ...) EINFO_XPRINTF;
+int eerror (const char *fmt, ...) EINFO_PRINTF;
+void eerrorx (const char *fmt, ...) EINFO_XPRINTF;
+
+int einfovn (const char *fmt, ...) EINFO_PRINTF;
+int ewarnvn (const char *fmt, ...) EINFO_PRINTF;
+int ebeginvn (const char *fmt, ...) EINFO_PRINTF;
+int eendvn (int retval, const char *fmt, ...) EEND_PRINTF;
+int ewendvn (int retval, const char *fmt, ...) EEND_PRINTF;
+int einfov (const char *fmt, ...) EINFO_PRINTF;
+int ewarnv (const char *fmt, ...) EINFO_PRINTF;
+/*@}*/
+
+/*! @ingroup ebegin
+ * @brief Display informational messages that may take some time.
+ *
+ * Similar to einfo, but we add ... to the end of the message */
+/*@{*/
+int ebeginv (const char *fmt, ...) EINFO_PRINTF;
+int ebegin (const char *fmt, ...) EINFO_PRINTF;
+/*@}*/
+
+/*! @ingroup eend
+ * @brief End an ebegin.
+ *
+ * If you ebegin, you should eend also.
+ * eend places [ ok ] or [ !! ] at the end of the terminal line depending on
+ * retval (0 or ok, anything else for !!)
+ *
+ * ebracket allows you to specifiy the position, color and message */
+/*@{*/
+int eend (int retval, const char *fmt, ...) EEND_PRINTF;
+int ewend (int retval, const char *fmt, ...) EEND_PRINTF;
 void ebracket (int col, einfo_color_t color, const char *msg);
+
+int eendv (int retval, const char *fmt, ...) EEND_PRINTF;
+int ewendv (int retval, const char *fmt, ...) EEND_PRINTF;
+/*@}*/
+
+/*! @ingroup eindent
+ * @brief Indents the einfo lines.
+ *
+ * For each indent you should outdent when done */
+/*@{*/
 void eindent (void);
 void eoutdent (void);
-
-int einfovn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int ewarnvn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int ebeginvn (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int eendvn (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
-int ewendvn (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
-int einfov (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int ewarnv (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int ebeginv (const char *fmt, ...) EINFO_PRINTF (1, 2);
-int eendv (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
-int ewendv (int retval, const char *fmt, ...) EINFO_PRINTF (2, 3);
 void eindentv (void);
 void eoutdentv (void);
 
-/* Pointer to a string that is always prefixed to einfo/ewarn/error */
+/*! @brief Prefix each einfo line with something */
 void eprefix (const char *prefix);
 
 #endif