all places: doxygen cleanups

I see no errors with these changes using doxygen 1.8.1.1 .

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

8 files changed, 108 insertions, 85 deletions

diff --git a/include/control_external.h b/include/control_external.h
index e98f4d6d..12958e70 100644
--- a/include/control_external.h
+++ b/include/control_external.h
@@ -60,6 +60,11 @@ typedef struct snd_ctl_ext snd_ctl_ext_t;
 typedef struct snd_ctl_ext_callback snd_ctl_ext_callback_t;
 /** Key to access a control pointer */
 typedef unsigned long snd_ctl_ext_key_t;
+#ifdef DOC_HIDDEN
+/* redefine typedef's for stupid doxygen */
+typedef snd_ctl_ext snd_ctl_ext_t;
+typedef snd_ctl_ext_callback snd_ctl_ext_callback_t;
+#endif
 /** Callback to handle TLV commands. */
 typedef int (snd_ctl_ext_tlv_rw_t)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int op_flag, unsigned int numid,
 				   unsigned int *tlv, unsigned int tlv_size);
@@ -138,7 +143,7 @@ struct snd_ctl_ext {
 	} tlv;
 };
 
-/** Callback table of ext */
+/** Callback table of ext. */
 struct snd_ctl_ext_callback {
 	/**
 	 * close the control handle; optional
diff --git a/include/error.h b/include/error.h
index 256cd5f5..38ee0704 100644
--- a/include/error.h
+++ b/include/error.h
@@ -74,6 +74,7 @@ extern int snd_lib_error_set_handler(snd_lib_error_handler_t handler);
 }
 #endif
 
+/** Local error handler function type */
 typedef void (*snd_local_error_handler_t)(const char *file, int line,
 					  const char *func, int err,
 					  const char *fmt, va_list arg);
diff --git a/include/mixer.h b/include/mixer.h
index 58256a63..066d9784 100644
--- a/include/mixer.h
+++ b/include/mixer.h
@@ -154,7 +154,7 @@ void *snd_mixer_class_get_private(const snd_mixer_class_t *class_);
 snd_mixer_compare_t snd_mixer_class_get_compare(const snd_mixer_class_t *class_);
 int snd_mixer_class_set_event(snd_mixer_class_t *class_, snd_mixer_event_t event);
 int snd_mixer_class_set_private(snd_mixer_class_t *class_, void *private_data);
-int snd_mixer_class_set_private_free(snd_mixer_class_t *class_, void (*private_free)(snd_mixer_class_t *class_));
+int snd_mixer_class_set_private_free(snd_mixer_class_t *class_, void (*private_free)(snd_mixer_class_t *));
 int snd_mixer_class_set_compare(snd_mixer_class_t *class_, snd_mixer_compare_t compare);
 
 /**
diff --git a/include/pcm.h b/include/pcm.h
index 549d6292..d94ba90d 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -491,43 +491,43 @@ enum snd_pcm_chmap_type {
 
 /** channel positions */
 enum snd_pcm_chmap_position {
-	SND_CHMAP_UNKNOWN = 0,	/** unspecified */
-	SND_CHMAP_NA,		/** N/A, silent */
-	SND_CHMAP_MONO,		/** mono stream */
-	SND_CHMAP_FL,		/** front left */
-	SND_CHMAP_FR,		/** front right */
-	SND_CHMAP_RL,		/** rear left */
-	SND_CHMAP_RR,		/** rear right */
-	SND_CHMAP_FC,		/** front center */
-	SND_CHMAP_LFE,		/** LFE */
-	SND_CHMAP_SL,		/** side left */
-	SND_CHMAP_SR,		/** side right */
-	SND_CHMAP_RC,		/** rear center */
-	SND_CHMAP_FLC,		/** front left center */
-	SND_CHMAP_FRC,		/** front right center */
-	SND_CHMAP_RLC,		/** rear left center */
-	SND_CHMAP_RRC,		/** rear right center */
-	SND_CHMAP_FLW,		/** front left wide */
-	SND_CHMAP_FRW,		/** front right wide */
-	SND_CHMAP_FLH,		/** front left high */
-	SND_CHMAP_FCH,		/** front center high */
-	SND_CHMAP_FRH,		/** front right high */
-	SND_CHMAP_TC,		/** top center */
-	SND_CHMAP_TFL,		/** top front left */
-	SND_CHMAP_TFR,		/** top front right */
-	SND_CHMAP_TFC,		/** top front center */
-	SND_CHMAP_TRL,		/** top rear left */
-	SND_CHMAP_TRR,		/** top rear right */
-	SND_CHMAP_TRC,		/** top rear center */
-	SND_CHMAP_TFLC,		/* top front left center */
-	SND_CHMAP_TFRC,		/* top front right center */
-	SND_CHMAP_TSL,		/* top side left */
-	SND_CHMAP_TSR,		/* top side right */
-	SND_CHMAP_LLFE,		/* left LFE */
-	SND_CHMAP_RLFE,		/* right LFE */
-	SND_CHMAP_BC,		/* bottom center */
-	SND_CHMAP_BLC,		/* bottom left center */
-	SND_CHMAP_BRC,		/* bottom right center */
+	SND_CHMAP_UNKNOWN = 0,	/**< unspecified */
+	SND_CHMAP_NA,		/**< N/A, silent */
+	SND_CHMAP_MONO,		/**< mono stream */
+	SND_CHMAP_FL,		/**< front left */
+	SND_CHMAP_FR,		/**< front right */
+	SND_CHMAP_RL,		/**< rear left */
+	SND_CHMAP_RR,		/**< rear right */
+	SND_CHMAP_FC,		/**< front center */
+	SND_CHMAP_LFE,		/**< LFE */
+	SND_CHMAP_SL,		/**< side left */
+	SND_CHMAP_SR,		/**< side right */
+	SND_CHMAP_RC,		/**< rear center */
+	SND_CHMAP_FLC,		/**< front left center */
+	SND_CHMAP_FRC,		/**< front right center */
+	SND_CHMAP_RLC,		/**< rear left center */
+	SND_CHMAP_RRC,		/**< rear right center */
+	SND_CHMAP_FLW,		/**< front left wide */
+	SND_CHMAP_FRW,		/**< front right wide */
+	SND_CHMAP_FLH,		/**< front left high */
+	SND_CHMAP_FCH,		/**< front center high */
+	SND_CHMAP_FRH,		/**< front right high */
+	SND_CHMAP_TC,		/**< top center */
+	SND_CHMAP_TFL,		/**< top front left */
+	SND_CHMAP_TFR,		/**< top front right */
+	SND_CHMAP_TFC,		/**< top front center */
+	SND_CHMAP_TRL,		/**< top rear left */
+	SND_CHMAP_TRR,		/**< top rear right */
+	SND_CHMAP_TRC,		/**< top rear center */
+	SND_CHMAP_TFLC,		/**< top front left center */
+	SND_CHMAP_TFRC,		/**< top front right center */
+	SND_CHMAP_TSL,		/**< top side left */
+	SND_CHMAP_TSR,		/**< top side right */
+	SND_CHMAP_LLFE,		/**< left LFE */
+	SND_CHMAP_RLFE,		/**< right LFE */
+	SND_CHMAP_BC,		/**< bottom center */
+	SND_CHMAP_BLC,		/**< bottom left center */
+	SND_CHMAP_BRC,		/**< bottom right center */
 	SND_CHMAP_LAST = SND_CHMAP_BRC,
 };
 
@@ -541,14 +541,14 @@ enum snd_pcm_chmap_position {
 
 /** the channel map header */
 typedef struct snd_pcm_chmap {
-	unsigned int channels;	/** number of channels */
-	unsigned int pos[0];	/** channel position array */
+	unsigned int channels;	/**< number of channels */
+	unsigned int pos[0];	/**< channel position array */
 } snd_pcm_chmap_t;
 
 /** the header of array items returned from snd_pcm_query_chmaps() */
 typedef struct snd_pcm_chmap_query {
-	enum snd_pcm_chmap_type type;	/** channel map type */
-	snd_pcm_chmap_t map;		/** available channel map */
+	enum snd_pcm_chmap_type type;	/**< channel map type */
+	snd_pcm_chmap_t map;		/**< available channel map */
 } snd_pcm_chmap_query_t;
 
 
diff --git a/include/pcm_extplug.h b/include/pcm_extplug.h
index 4eb10c76..884f3221 100644
--- a/include/pcm_extplug.h
+++ b/include/pcm_extplug.h
@@ -49,6 +49,11 @@ enum {
 typedef struct snd_pcm_extplug snd_pcm_extplug_t;
 /** Callback table of extplug */
 typedef struct snd_pcm_extplug_callback snd_pcm_extplug_callback_t;
+#ifdef DOC_HIDDEN
+/* redefine typedefs for stupid doxygen */
+typedef snd_pcm_extplug snd_pcm_extplug_t;
+typedef snd_pcm_extplug_callback snd_pcm_extplug_callback_t;
+#endif
 
 /*
  * Protocol version
diff --git a/include/pcm_ioplug.h b/include/pcm_ioplug.h
index 25202fd9..e529e6a6 100644
--- a/include/pcm_ioplug.h
+++ b/include/pcm_ioplug.h
@@ -54,6 +54,11 @@ enum {
 typedef struct snd_pcm_ioplug snd_pcm_ioplug_t;
 /** Callback table of ioplug */
 typedef struct snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t;
+#ifdef DOC_HIDDEN
+/* redefine typedefs for stupid doxygen */
+typedef snd_pcm_ioplug snd_pcm_ioplug_t;
+typedef snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t;
+#endif
 
 /*
  * bit flags for additional conditions
diff --git a/include/seq_event.h b/include/seq_event.h
index 583f1d06..6bd0de3b 100644
--- a/include/seq_event.h
+++ b/include/seq_event.h
@@ -254,10 +254,16 @@ typedef struct snd_seq_ev_raw32 {
 } snd_seq_ev_raw32_t;
 
 /** external stored data */
-typedef struct snd_seq_ev_ext {
+struct snd_seq_ev_ext {
 	unsigned int len;		/**< length of data */
 	void *ptr;			/**< pointer to data (note: can be 64-bit) */
-} __attribute__((packed)) snd_seq_ev_ext_t;
+} __attribute__((packed));
+/** external stored data */
+typedef struct snd_seq_ev_ext snd_seq_ev_ext_t;
+#ifdef DOC_HIDDEN
+/* redefine typedef for stupid doxygen */
+typedef snd_seq_ev_ext snd_seq_ev_ext_t;
+#endif
 
 /** Result events */
 typedef struct snd_seq_result {
diff --git a/include/use-case.h b/include/use-case.h
index c37c842a..defd4ea9 100644
--- a/include/use-case.h
+++ b/include/use-case.h
@@ -49,7 +49,8 @@ extern "C" {
  *  \{
  */
 
-/**
+/*! \page Usecase ALSA Use Case Interface
+ * 
  * ALSA Use Case Interface
  *
  * The use case manager works by configuring the sound card ALSA kcontrols to
@@ -96,15 +97,15 @@ extern "C" {
  * case verb will configure the audio hardware for HiFi Music playback
  * and capture.
  */
-#define SND_USE_CASE_VERB_INACTIVE		"Inactive"
-#define SND_USE_CASE_VERB_HIFI			"HiFi"
-#define SND_USE_CASE_VERB_HIFI_LOW_POWER	"HiFi Low Power"
-#define SND_USE_CASE_VERB_VOICE			"Voice"
-#define SND_USE_CASE_VERB_VOICE_LOW_POWER	"Voice Low Power"
-#define SND_USE_CASE_VERB_VOICECALL		"Voice Call"
-#define SND_USE_CASE_VERB_IP_VOICECALL		"Voice Call IP"
-#define SND_USE_CASE_VERB_ANALOG_RADIO		"FM Analog Radio"
-#define SND_USE_CASE_VERB_DIGITAL_RADIO		"FM Digital Radio"
+#define SND_USE_CASE_VERB_INACTIVE		"Inactive"		/**< Inactive Verb */
+#define SND_USE_CASE_VERB_HIFI			"HiFi"			/**< HiFi Verb */
+#define SND_USE_CASE_VERB_HIFI_LOW_POWER	"HiFi Low Power"	/**< HiFi Low Power Verb */
+#define SND_USE_CASE_VERB_VOICE			"Voice"			/**< Voice Verb */
+#define SND_USE_CASE_VERB_VOICE_LOW_POWER	"Voice Low Power"	/**< Voice Low Power Verb */
+#define SND_USE_CASE_VERB_VOICECALL		"Voice Call"		/**< Voice Call Verb */
+#define SND_USE_CASE_VERB_IP_VOICECALL		"Voice Call IP"		/**< Voice Call IP Verb */
+#define SND_USE_CASE_VERB_ANALOG_RADIO		"FM Analog Radio"	/**< FM Analog Radio Verb */
+#define SND_USE_CASE_VERB_DIGITAL_RADIO		"FM Digital Radio"	/**< FM Digital Radio Verb */
 /* add new verbs to end of list */
 
 
@@ -114,16 +115,16 @@ extern "C" {
  * Physical system devices the render and capture audio. Devices can be OR'ed
  * together to support audio on simultaneous devices.
  */
-#define SND_USE_CASE_DEV_NONE		"None"
-#define SND_USE_CASE_DEV_SPEAKER	"Speaker"
-#define SND_USE_CASE_DEV_LINE		"Line"
-#define SND_USE_CASE_DEV_HEADPHONES	"Headphones"
-#define SND_USE_CASE_DEV_HEADSET	"Headset"
-#define SND_USE_CASE_DEV_HANDSET	"Handset"
-#define SND_USE_CASE_DEV_BLUETOOTH	"Bluetooth"
-#define SND_USE_CASE_DEV_EARPIECE	"Earpiece"
-#define SND_USE_CASE_DEV_SPDIF		"SPDIF"
-#define SND_USE_CASE_DEV_HDMI		"HDMI"
+#define SND_USE_CASE_DEV_NONE		"None"		/**< None Device */
+#define SND_USE_CASE_DEV_SPEAKER	"Speaker"	/**< Speaker Device */
+#define SND_USE_CASE_DEV_LINE		"Line"		/**< Line Device */
+#define SND_USE_CASE_DEV_HEADPHONES	"Headphones"	/**< Headphones Device */
+#define SND_USE_CASE_DEV_HEADSET	"Headset"	/**< Headset Device */
+#define SND_USE_CASE_DEV_HANDSET	"Handset"	/**< Handset Device */
+#define SND_USE_CASE_DEV_BLUETOOTH	"Bluetooth"	/**< Bluetooth Device */
+#define SND_USE_CASE_DEV_EARPIECE	"Earpiece"	/**< Earpiece Device */
+#define SND_USE_CASE_DEV_SPDIF		"SPDIF"		/**< SPDIF Device */
+#define SND_USE_CASE_DEV_HDMI		"HDMI"		/**< HDMI Device */
 /* add new devices to end of list */
 
 
@@ -145,12 +146,12 @@ extern "C" {
  *  3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
  *     ringtone pcm data.
  */
-#define SND_USE_CASE_MOD_CAPTURE_VOICE		"Capture Voice"
-#define SND_USE_CASE_MOD_CAPTURE_MUSIC		"Capture Music"
-#define SND_USE_CASE_MOD_PLAY_MUSIC		"Play Music"
-#define SND_USE_CASE_MOD_PLAY_VOICE		"Play Voice"
-#define SND_USE_CASE_MOD_PLAY_TONE		"Play Tone"
-#define SND_USE_CASE_MOD_ECHO_REF		"Echo Reference"
+#define SND_USE_CASE_MOD_CAPTURE_VOICE		"Capture Voice"		/**< Capture Voice Modifier */
+#define SND_USE_CASE_MOD_CAPTURE_MUSIC		"Capture Music"		/**< Capture Music Modifier */
+#define SND_USE_CASE_MOD_PLAY_MUSIC		"Play Music"		/**< Play Music Modifier */
+#define SND_USE_CASE_MOD_PLAY_VOICE		"Play Voice"		/**< Play Voice Modifier */
+#define SND_USE_CASE_MOD_PLAY_TONE		"Play Tone"		/**< Play Tone Modifier */
+#define SND_USE_CASE_MOD_ECHO_REF		"Echo Reference"	/**< Echo Reference Modifier */
 /* add new modifiers to end of list */
 
 
@@ -162,9 +163,9 @@ extern "C" {
  * audio driver in order to lower power consumption.
  *
  */
-#define SND_USE_CASE_TQ_MUSIC		"Music"
-#define SND_USE_CASE_TQ_VOICE		"Voice"
-#define SND_USE_CASE_TQ_TONES		"Tones"
+#define SND_USE_CASE_TQ_MUSIC		"Music"		/**< Music Tone Quality */
+#define SND_USE_CASE_TQ_VOICE		"Voice"		/**< Voice Tone Quality */
+#define SND_USE_CASE_TQ_TONES		"Tones"		/**< Tones Tone Quality */
 
 /** use case container */
 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
@@ -197,16 +198,16 @@ int snd_use_case_free_list(const char *list[], int items);
  *			  (in pair cardname+comment)
  *   _verbs		- get verb list
  *			  (in pair verb+comment)
- *   _devices[/<verb>]	- get list of supported devices
+ *   _devices[/{verb}]	- get list of supported devices
  *			  (in pair device+comment)
- *   _modifiers[/<verb>]- get list of supported modifiers
+ *   _modifiers[/{verb}]- get list of supported modifiers
  *			  (in pair modifier+comment)
- *   TQ[/<verb>]	- get list of TQ identifiers
+ *   TQ[/{verb}]	- get list of TQ identifiers
  *   _enadevs		- get list of enabled devices
  *   _enamods		- get list of enabled modifiers
  *
- *   _supporteddevs/<modifier>|<device>[/<verb>]   - list of supported devices
- *   _conflictingdevs/<modifier>|<device>[/<verb>] - list of conflicting devices
+ *   _supporteddevs/{modifier}|{device}[/{verb}]   - list of supported devices
+ *   _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
  *   Note that at most one of the supported/conflicting devs lists has
  *   any entries, and when neither is present, all devices are supported.
  *
@@ -230,8 +231,8 @@ int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
  *   NULL 		- return current card
  *   _verb		- return current verb
  *
- *   [=]<NAME>[/[<modifier>|</device>][/<verb>]]
- *                      - value identifier <NAME>
+ *   [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
+ *                      - value identifier {NAME}
  *                      - Search starts at given modifier or device if any,
  *                          else at a verb
  *                      - Search starts at given verb if any,
@@ -281,8 +282,8 @@ int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
  * \return Zero if success, otherwise a negative error code
  *
  * Known identifiers:
- *   _devstatus/<device>	- return status for given device
- *   _modstatus/<modifier>	- return status for given modifier
+ *   _devstatus/{device}	- return status for given device
+ *   _modstatus/{modifier}	- return status for given modifier
  */
 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
 		      const char *identifier,
@@ -299,13 +300,13 @@ int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
  *   _verb 		- set current verb = value
  *   _enadev		- enable given device = value
  *   _disdev		- disable given device = value
- *   _swdev/<old_device> - new_device = value
+ *   _swdev/{old_device} - new_device = value
  *			- disable old_device and then enable new_device
  *			- if old_device is not enabled just return
  *			- check transmit sequence firstly
  *   _enamod		- enable given modifier = value
  *   _dismod		- disable given modifier = value
- *   _swmod/<old_modifier> - new_modifier = value
+ *   _swmod/{old_modifier} - new_modifier = value
  *			- disable old_modifier and then enable new_modifier
  *			- if old_modifier is not enabled just return
  *			- check transmit sequence firstly