From b5f50b06d207637ac4294ea69e8310f8bd41bc27 Mon Sep 17 00:00:00 2001
From: Clemens Ladisch <clemens@ladisch.de>
Date: Wed, 12 Oct 2005 16:08:53 +0000
Subject: [PATCH] fix doxygen warnings

Fix some wrong parameter names, hide some undocumented functions, and
correctly escape <> characters.
---
 src/conf.c              |  2 +-
 src/mixer/mixer.c       | 12 ++++++------
 src/mixer/simple.c      |  6 +++++-
 src/mixer/simple_abst.c |  8 ++++++--
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/conf.c b/src/conf.c
index da8bc458..9a8591fc 100644
--- a/src/conf.c
+++ b/src/conf.c
@@ -364,7 +364,7 @@ Several built-in functions are available.</P>
 
 <P>A function is defined with the id \c \@func and the function name. All other
 values in the current compound are used as configuration for the function.
-If the compound func.<function_name> is defined in the root node, then the
+If the compound func.\<function_name\> is defined in the root node, then the
 library and function from this compound configuration are used, otherwise
 'snd_func_' is prefixed to the string and code from the ALSA library is used.
 The definition of a function looks like:</P> 
diff --git a/src/mixer/mixer.c b/src/mixer/mixer.c
index 33298231..5ef0ba79 100644
--- a/src/mixer/mixer.c
+++ b/src/mixer/mixer.c
@@ -214,7 +214,7 @@ int snd_mixer_attach(snd_mixer_t *mixer, const char *name)
 /**
  * \brief Attach an HCTL to an opened mixer
  * \param mixer Mixer handle
- * \param name HCTL name (see #snd_hctl_open)
+ * \param hctl the HCTL to be attached
  * \return 0 on success otherwise a negative error code
  */
 int snd_mixer_attach_hctl(snd_mixer_t *mixer, snd_hctl_t *hctl)
@@ -645,7 +645,6 @@ static int mixer_compare(const void *a, const void *b)
 	return mixer->compare(*(const snd_mixer_elem_t * const *)a, *(const snd_mixer_elem_t * const *)b);
 }
 
-typedef int (*qsort_func)(const void *, const void *);
 static int snd_mixer_sort(snd_mixer_t *mixer)
 {
 	unsigned int k;
@@ -856,8 +855,8 @@ int snd_mixer_handle_events(snd_mixer_t *mixer)
 
 /**
  * \brief Set callback function for a mixer
- * \param mixer mixer handle
- * \param callback callback function
+ * \param obj mixer handle
+ * \param val callback function
  */
 void snd_mixer_set_callback(snd_mixer_t *obj, snd_mixer_callback_t val)
 {
@@ -868,7 +867,7 @@ void snd_mixer_set_callback(snd_mixer_t *obj, snd_mixer_callback_t val)
 /**
  * \brief Set callback private value for a mixer
  * \param mixer mixer handle
- * \param callback_private callback private value
+ * \param val callback private value
  */
 void snd_mixer_set_callback_private(snd_mixer_t *mixer, void * val)
 {
@@ -968,7 +967,7 @@ int snd_mixer_class_malloc(snd_mixer_class_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_mixer_class_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_mixer_class_free(snd_mixer_class_t *obj)
 {
@@ -1075,6 +1074,7 @@ int snd_mixer_class_set_private_free(snd_mixer_class_t *obj, void (*private_free
 /**
  * \brief Set mixer compare callback to given mixer class
  * \param obj Mixer simple class identifier
+ * \param compare the compare callback to be used
  * \return zero if success, otherwise a negative error code
  */
 int snd_mixer_class_set_compare(snd_mixer_class_t *obj, snd_mixer_compare_t compare)
diff --git a/src/mixer/simple.c b/src/mixer/simple.c
index 621ab219..2d90dfd4 100644
--- a/src/mixer/simple.c
+++ b/src/mixer/simple.c
@@ -79,6 +79,8 @@ int snd_mixer_selem_register(snd_mixer_t *mixer,
 	return -ENXIO;
 }
 
+#ifndef DOC_HIDDEN
+
 #define CHECK_BASIC(xelem) \
 { \
 	assert(xelem); \
@@ -108,6 +110,8 @@ int snd_mixer_selem_register(snd_mixer_t *mixer,
 #define COND_CAPS(xelem, what) \
 	!!(((sm_selem_t *)(elem)->private_data)->caps & (what))
 
+#endif /* !DOC_HIDDEN */
+
 #ifndef DOC_HIDDEN
 int snd_mixer_selem_compare(const snd_mixer_elem_t *c1, const snd_mixer_elem_t *c2)
 {
@@ -931,7 +935,7 @@ int snd_mixer_selem_id_malloc(snd_mixer_selem_id_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_mixer_selem_id_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_mixer_selem_id_free(snd_mixer_selem_id_t *obj)
 {
diff --git a/src/mixer/simple_abst.c b/src/mixer/simple_abst.c
index 0a88dc09..789216dc 100644
--- a/src/mixer/simple_abst.c
+++ b/src/mixer/simple_abst.c
@@ -39,6 +39,8 @@
 #include "asoundlib.h"
 #include "mixer_simple.h"
 
+#ifndef DOC_HIDDEN
+
 #define SO_PATH PKGLIBDIR "/smixer"
 
 typedef struct _class_priv {
@@ -54,6 +56,8 @@ typedef struct _class_priv {
 
 typedef int (*snd_mixer_sbasic_init_t)(snd_mixer_class_t *class);
 
+#endif /* !DOC_HIDDEN */
+
 static int try_open(snd_mixer_class_t *class, const char *lib)
 {
 	class_priv_t *priv = snd_mixer_class_get_private(class);
@@ -324,9 +328,9 @@ void snd_mixer_sbasic_set_private(const snd_mixer_class_t *class, void *private_
 }
 
 /**
- * \brief Set private data for basic abstraction
+ * \brief Set private data free callback for basic abstraction
  * \param class Mixer class
- * \param private_data Private data
+ * \param private_free free callback for private data
  */
 void snd_mixer_sbasic_set_private_free(const snd_mixer_class_t *class, void (*private_free)(snd_mixer_class_t *class))
 {
-- 
2.47.1