Documentation update by Clement Ladish

1 files changed, 22 insertions, 19 deletions

diff --git a/include/error.h b/include/error.h
index c2100ea4..c1915bd1 100644
--- a/include/error.h
+++ b/include/error.h
@@ -7,8 +7,8 @@
  * \date 1998-2001
  *
  * Application interface library for the ALSA driver
- *
- *
+ */
+/*
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Lesser General Public License as
  *   published by the Free Software Foundation; either version 2.1 of
@@ -34,34 +34,37 @@ extern "C" {
 
 /**
  *  \defgroup Error Error handling
- *  Error handling
+ *  Error handling macros and functions.
  *  \{
  */
 
-#define SND_ERROR_BEGIN				500000			/**< begin boundary of sound error codes */
-#define SND_ERROR_INCOMPATIBLE_VERSION		(SND_ERROR_BEGIN+0)	/**< protocol is not compatible */
+#define SND_ERROR_BEGIN				500000			/**< Lower boundary of sound error codes. */
+#define SND_ERROR_INCOMPATIBLE_VERSION		(SND_ERROR_BEGIN+0)	/**< Kernel/library protocols are not compatible. */
 
 const char *snd_strerror(int errnum);
 
 /**
- * \brief Error handler
- * \param file File name
- * \param line Line number
- * \param function Function name
- * \param err errno value (or 0 if not relevant)
- * \param fmt printf(3) format
- * \param ... printf(3) arguments
+ * \brief Error handler callback.
+ * \param file Source file name.
+ * \param line Line number.
+ * \param function Function name.
+ * \param err Value of \c errno, or 0 if not relevant.
+ * \param fmt \c printf(3) format.
+ * \param ... \c printf(3) arguments.
+ *
+ * A function of this type is called by the ALSA library when an error occurs.
+ * This function usually shows the message on the screen, and/or logs it.
  */
-typedef void (snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((format (printf, 5, 6))) */;
-extern snd_lib_error_handler_t *snd_lib_error;
-extern int snd_lib_error_set_handler(snd_lib_error_handler_t *handler);
+typedef void (*snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((format (printf, 5, 6))) */;
+extern snd_lib_error_handler_t snd_lib_error;
+extern int snd_lib_error_set_handler(snd_lib_error_handler_t handler);
 
 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 95)
-#define SNDERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, __VA_ARGS__) /**< show sound error */
-#define SYSERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, __VA_ARGS__) /**< show system error */
+#define SNDERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, __VA_ARGS__) /**< Shows a sound error message. */
+#define SYSERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, __VA_ARGS__) /**< Shows a system error message (related to \c errno). */
 #else
-#define SNDERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, ##args) /**< show sound error */
-#define SYSERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, ##args) /**< show system error */
+#define SNDERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, ##args) /**< Shows a sound error message. */
+#define SYSERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, ##args) /**< Shows a system error message (related to \c errno). */
 #endif
 
 /** \} */