--- a/src/error.h	Tue Mar 10 03:48:00 2009 +0200
+++ b/src/error.h	Tue Mar 10 19:52:38 2009 +0200
@@ -1,14 +1,16 @@
 #ifndef ERROR_H
 #define ERROR_H
 
-/*
+/**
+ * @file
+ *
  * Error-handling functions
  */
 #include <errno.h>
 
-/*
- * Type used for error codes is an explicitly *unsigned* int, meaning that error codes themselves are positive.
- * Negative error codes also exist in some places, and they are just a negative err_t.
+/**
+ * The type used for error codes is an explicitly *unsigned* int, meaning that error codes themselves are positive.
+ * Negative error codes (as signed ints) also exist in some places, and they are just a negative err_t.
  */
 typedef unsigned int err_t;
 
@@ -16,6 +18,7 @@
  * Ways to interpret error_info.extra
  */
 enum error_extra_types {
+    /** No extra info */
     ERR_EXTRA_NONE      = 0,
 
     /** libc errno, using strerror() */
@@ -24,7 +27,7 @@
     /** libc resolver, using gai_strerror() */
     ERR_EXTRA_GAI,
 
-    /** gnutls, using gnutls_strerror() */
+    /** GnuTLS, using gnutls_strerror() */
     ERR_EXTRA_GNUTLS,
 };
 
@@ -82,28 +85,28 @@
     enum error_extra_types extra_type;
 };
 
-/*
+/**
  * An error code and associated extra infos
  */
 struct error_info {
-    /* The base error code */
+    /** The base error code */
     err_t code;
 
-    /* Additional detail info, usually some third-party error code */
+    /** Additional detail info, usually some third-party error code, as defined by the code's ERR_EXTRA_* */
     int extra;
 };
 
-/*
+/**
  * Translate an err_t into a function name.
  */
 const char *error_name (err_t code);
 
-/*
+/**
  * Maximum length of error messages returned by error_msg (including NUL byte)
  */
 #define ERROR_MSG_MAXLEN 1024
 
-/*
+/**
  * Translate an error_info into a message.
  *
  * This is returned as a pointer into a statically allocated buffer. It is not re-entrant.
@@ -113,42 +116,42 @@
 /** No error, evaulates as logical false */
 #define SUCCESS (0)
 
-/* Evaulates to error_info.code as lvalue */
+/** Evaulates to error_info.code as lvalue */
 #define ERROR_CODE(err_info_ptr) ((err_info_ptr)->code)
 
-/* Evaulates to error_info.extra as lvalue */
+/** Evaulates to error_info.extra as lvalue */
 #define ERROR_EXTRA(err_info_ptr) ((err_info_ptr)->extra)
 
-/* Set error_info.code to SUCCESS, evaulates as zero */
+/** Set error_info.code to SUCCESS, evaulates as zero */
 #define RESET_ERROR(err_info_ptr) ((err_info_ptr)->code = SUCCESS)
 
-/* Compare error_info.code != 0 */
+/** Compare error_info.code != 0 */
 #define IS_ERROR(err_info_ptr) (!!(err_info_ptr)->code)
 
-/* Compare the err_code/err_extra for an err_info */
+/** Compare the err_code/err_extra for an err_info */
 #define MATCH_ERROR(err_info_ptr, err_code, err_extra) ((err_info_ptr)->code == (err_code) && (err_info_ptr)->extra == (err_extra))
 
-/* Set error_info.code, but leave err_extra as-is. Evaluates to err_code */
+/** Set error_info.code, but leave err_extra as-is. Evaluates to err_code */
 #define SET_ERROR(err_info_ptr, err_code) ((err_info_ptr)->code = (err_code))
 
-/* Set error_info.code/extra. XXX: should evaluate to err_code */
+/** Set error_info.code/extra. XXX: should evaluate to err_code */
 #define _SET_ERROR_EXTRA(err_info_ptr, err_code, err_extra) (err_info_ptr)->code = (err_code); (err_info_ptr)->extra = (err_extra)
 #define SET_ERROR_EXTRA(err_info_ptr, err_code, err_extra) do { _SET_ERROR_EXTRA(err_info_ptr, err_code, err_extra); } while (0)
 
-/* Set error_info.code to err_code, and .extra to errno. XXX: should evaulate to err_code */
+/** Set error_info.code to err_code, and .extra to errno. XXX: should evaulate to err_code */
 #define _SET_ERROR_ERRNO(err_info_ptr, err_code) _SET_ERROR_EXTRA(err_info_ptr, err_code, errno);
 #define SET_ERROR_ERRNO(err_info_ptr, err_code) SET_ERROR_EXTRA(err_info_ptr, err_code, errno);
 
-/* Set error_info from another error_info. Evaluates to the new error_info */
+/** Set error_info from another error_info. Evaluates to the new error_info */
 #define SET_ERROR_INFO(err_info_ptr, from_ptr) (*err_info_ptr = *from_ptr)
 
-/* Same as above, but also return err_code from func. XXX: use 'return SET_ERROR...' instead */
+/** Same as above, but also return err_code from func. XXX: use 'return SET_ERROR...' instead */
 #define RETURN_SET_ERROR(err_info_ptr, err_code) do { SET_ERROR(err_info_ptr, err_code); return (err_code); } while (0)
 #define RETURN_SET_ERROR_EXTRA(err_info_ptr, err_code, err_extra) do { _SET_ERROR_EXTRA(err_info_ptr, err_code, err_extra); return (err_code); } while (0)
 #define RETURN_SET_ERROR_ERRNO(err_info_ptr, err_code) do { _SET_ERROR_ERRNO(err_info_ptr, err_code); return (err_code); } while (0)
 #define RETURN_SET_ERROR_INFO(err_info_ptr, from_ptr) do { SET_ERROR_INFO(err_info_ptr, from_ptr); return (from_ptr->code); } while (0)
 
-/* Same as above, but also do a 'goto error' */
+/** Same as above, but also do a 'goto error' */
 #define JUMP_SET_ERROR(err_info_ptr, err_code) do { SET_ERROR(err_info_ptr, err_code); goto error; } while (0)
 #define JUMP_SET_ERROR_INFO(err_info_ptr, from_ptr) do { SET_ERROR_INFO(err_info_ptr, from_ptr); goto error; } while (0)