From 1e4e8ed27ae95096255283e92a75738bc7e296e5 Mon Sep 17 00:00:00 2001 From: Roy Marples Date: Tue, 25 Sep 2007 15:38:21 +0000 Subject: Initial doxygen documentation for rc.h and einfo.h. Plus some header clean ups. --- src/einfo.h | 129 +++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 88 insertions(+), 41 deletions(-) (limited to 'src/einfo.h') 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 #include +/*! @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 -- cgit v1.2.3