More documentation enhancements / removal of non-existent functions.

18 files changed, 153 insertions, 12 deletions

diff --git a/include/conf.h b/include/conf.h
index 198e42cb..eea2958d 100644
--- a/include/conf.h
+++ b/include/conf.h
@@ -93,8 +93,6 @@ int snd_config_get_bool(snd_config_t *conf);
 int snd_config_get_ctl_iface_ascii(const char *ascii);
 int snd_config_get_ctl_iface(snd_config_t *conf);
 
-typedef int (snd_config_string_replace_callback_t)(const char *what, char **dst, void *private_data);
-
 int snd_config_refer_load(snd_config_t **dst, char **name,
 			  snd_config_t *root, snd_config_t *config);
 
diff --git a/include/control.h b/include/control.h
index d510419a..05b38f66 100644
--- a/include/control.h
+++ b/include/control.h
@@ -11,6 +11,7 @@
  *  \{
  */
 
+/** IEC958 structure */
 typedef struct sndrv_aes_iec958 snd_aes_iec958_t;
 
 /** CTL card info container */
@@ -393,7 +394,6 @@ int snd_hctl_load(snd_hctl_t *hctl);
 int snd_hctl_free(snd_hctl_t *hctl);
 int snd_hctl_handle_events(snd_hctl_t *hctl);
 const char *snd_hctl_name(snd_hctl_t *hctl);
-snd_ctl_type_t snd_hctl_type(snd_hctl_t *hctl);
 int snd_hctl_wait(snd_hctl_t *hctl, int timeout);
 
 snd_hctl_elem_t *snd_hctl_elem_next(snd_hctl_elem_t *elem);
diff --git a/include/hwdep.h b/include/hwdep.h
index 0983c922..67389e08 100644
--- a/include/hwdep.h
+++ b/include/hwdep.h
@@ -5,6 +5,12 @@
  *                                                                          *
  ****************************************************************************/
 
+/**
+ *  \defgroup HwDep Hardware Dependant Interface
+ *  The Hardware Dependant Interface.
+ *  \{
+ */
+
 /** HwDep information container */
 typedef struct _snd_hwdep_info snd_hwdep_info_t;
 
@@ -40,7 +46,22 @@ int snd_hwdep_ioctl(snd_hwdep_t *hwdep, unsigned int request, void * arg);
 ssize_t snd_hwdep_write(snd_hwdep_t *hwdep, const void *buffer, size_t size);
 ssize_t snd_hwdep_read(snd_hwdep_t *hwdep, void *buffer, size_t size);
 
+size_t snd_hwdep_info_sizeof(void);
+#define snd_hwdep_info_alloca(ptr) do { assert(ptr); *ptr = (snd_hwdep_info_t *) alloca(snd_hwdep_info_sizeof()); memset(*ptr, 0, snd_hwdep_info_sizeof()); } while (0)
+int snd_hwdep_info_malloc(snd_hwdep_info_t **ptr);
+void snd_hwdep_info_free(snd_hwdep_info_t *obj);
+void snd_hwdep_info_copy(snd_hwdep_info_t *dst, const snd_hwdep_info_t *src);
+
+unsigned int snd_hwdep_info_get_device(const snd_hwdep_info_t *obj);
+int snd_hwdep_info_get_card(const snd_hwdep_info_t *obj);
+const char *snd_hwdep_info_get_id(const snd_hwdep_info_t *obj);
+const char *snd_hwdep_info_get_name(const snd_hwdep_info_t *obj);
+snd_hwdep_iface_t snd_hwdep_info_get_iface(const snd_hwdep_info_t *obj);
+void snd_hwdep_info_set_device(snd_hwdep_info_t *obj, unsigned int val);
+
 #ifdef __cplusplus
 }
 #endif
 
+/** \} */
+
diff --git a/include/instr.h b/include/instr.h
index 47c33e83..29f14799 100644
--- a/include/instr.h
+++ b/include/instr.h
@@ -17,6 +17,7 @@
 extern "C" {
 #endif
 
+/** container for sequencer instrument header */
 typedef struct _snd_instr_header snd_instr_header_t;
 
 size_t snd_instr_header_sizeof(void);
diff --git a/include/pcm.h b/include/pcm.h
index 13634780..fa514422 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -738,6 +738,7 @@ void snd_pcm_info_set_device(snd_pcm_info_t *obj, unsigned int val);
 void snd_pcm_info_set_subdevice(snd_pcm_info_t *obj, unsigned int val);
 void snd_pcm_info_set_stream(snd_pcm_info_t *obj, snd_pcm_stream_t val);
 
+/** type of pcm hook */
 typedef enum _snd_pcm_hook_type {
 	SND_PCM_HOOK_TYPE_HW_PARAMS,
 	SND_PCM_HOOK_TYPE_HW_FREE,
@@ -745,7 +746,9 @@ typedef enum _snd_pcm_hook_type {
 	SND_PCM_HOOK_TYPE_LAST = SND_PCM_HOOK_TYPE_CLOSE,
 } snd_pcm_hook_type_t;
 
+/** PCM hook container */
 typedef struct _snd_pcm_hook snd_pcm_hook_t;
+/** PCM hook callback function */
 typedef int (*snd_pcm_hook_func_t)(snd_pcm_hook_t *hook);
 snd_pcm_t *snd_pcm_hook_get_pcm(snd_pcm_hook_t *hook);
 void *snd_pcm_hook_get_private(snd_pcm_hook_t *hook);
diff --git a/include/rawmidi.h b/include/rawmidi.h
index 20ab4056..b982cd66 100644
--- a/include/rawmidi.h
+++ b/include/rawmidi.h
@@ -108,7 +108,6 @@ void snd_rawmidi_status_free(snd_rawmidi_status_t *obj);
 void snd_rawmidi_status_copy(snd_rawmidi_status_t *dst, const snd_rawmidi_status_t *src);
 void snd_rawmidi_status_get_tstamp(const snd_rawmidi_status_t *obj, snd_timestamp_t *ptr);
 size_t snd_rawmidi_status_get_avail(const snd_rawmidi_status_t *obj);
-size_t snd_rawmidi_status_get_avail_max(const snd_rawmidi_status_t *obj);
 size_t snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t *obj);
 int snd_rawmidi_status(snd_rawmidi_t *rmidi, snd_rawmidi_status_t * status);
 int snd_rawmidi_drain(snd_rawmidi_t *rmidi);
diff --git a/include/seq.h b/include/seq.h
index 6aa79a9c..59498059 100644
--- a/include/seq.h
+++ b/include/seq.h
@@ -32,6 +32,7 @@ do {\
  */
 #define SND_SEQ_NONBLOCK	1	/**< non-blocking mode */
 
+/** sequencer handle type */
 typedef enum _snd_seq_type {
 	SND_SEQ_TYPE_HW,		/**< hardware */
 	SND_SEQ_TYPE_SHM,		/**< shared memory (NYI) */
@@ -543,6 +544,7 @@ enum {
 	SND_SEQ_EVFLG_NOTE_ONEARG,
 	SND_SEQ_EVFLG_NOTE_TWOARG
 };
+
 enum {
 	SND_SEQ_EVFLG_QUEUE_NOARG,
 	SND_SEQ_EVFLG_QUEUE_TICK,
@@ -557,10 +559,11 @@ enum {
  */
 extern const unsigned int snd_seq_event_types[];
 
-#define _SND_SEQ_TYPE(x)	(1<<(x))	/* 24bit */
-#define _SND_SEQ_TYPE_OPT(x)	((x)<<24)	/* 8bit */
+#define _SND_SEQ_TYPE(x)	(1<<(x))	/**< master type - 24bit */
+#define _SND_SEQ_TYPE_OPT(x)	((x)<<24)	/**< optional type - 8bit */
 
-#define snd_seq_type_check(ev,x)	(snd_seq_event_types[(ev)->type] & _SND_SEQ_TYPE(x))
+/** check the event type */
+#define snd_seq_type_check(ev,x) (snd_seq_event_types[(ev)->type] & _SND_SEQ_TYPE(x))
 
 /** event type check: result events */
 #define snd_seq_ev_is_result_type(ev) \
diff --git a/include/seq_event.h b/include/seq_event.h
index fbc3f920..00cb953e 100644
--- a/include/seq_event.h
+++ b/include/seq_event.h
@@ -18,6 +18,7 @@
  */
 typedef unsigned char snd_seq_event_type_t;
 
+/** Sequencer event type */
 enum snd_seq_event_type {
 	/** system status; event data type = #snd_seq_result_t */
 	SND_SEQ_EVENT_SYSTEM = 0,
diff --git a/include/seq_midi_event.h b/include/seq_midi_event.h
index 5546490a..75f9645c 100644
--- a/include/seq_midi_event.h
+++ b/include/seq_midi_event.h
@@ -11,6 +11,7 @@
  *  \{
  */
 
+/** container for sequencer midi event parsers */
 typedef struct snd_midi_event snd_midi_event_t;
 
 #ifdef __cplusplus
diff --git a/src/async.c b/src/async.c
index 7c891f49..6d0e6541 100644
--- a/src/async.c
+++ b/src/async.c
@@ -1,3 +1,8 @@
+/**
+ * \file async.c
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2001
+ */
 /*
  *  Async notification helpers
  *  Copyright (c) 2001 by Abramo Bagnara <abramo@alsa-project.org>
@@ -23,6 +28,7 @@
 #include <signal.h>
 
 #ifdef SND_ASYNC_RT_SIGNAL
+/** async signal number */
 int snd_async_signo;
 void snd_async_init(void) __attribute__ ((constructor));
 
@@ -35,6 +41,7 @@ void snd_async_init(void)
 	}
 }
 #else
+/** async signal number */
 int snd_async_signo = SIGIO;
 #endif
 
@@ -55,6 +62,14 @@ static void snd_async_handler(int signo ATTRIBUTE_UNUSED, siginfo_t *siginfo, vo
 	}
 }
 
+/**
+ * \brief Add async handler
+ * \param handler Result - async handler
+ * \param fd - File descriptor
+ * \param callback - Async callback
+ * \param private_data - Private data for async callback
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_async_add_handler(snd_async_handler_t **handler, int fd, 
 			  snd_async_callback_t callback, void *private_data)
 {
@@ -84,6 +99,11 @@ int snd_async_add_handler(snd_async_handler_t **handler, int fd,
 	return 0;
 }
 
+/**
+ * \brief Delete async handler
+ * \param handler Async handler to delete
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_async_del_handler(snd_async_handler_t *handler)
 {
 	int err = 0;
@@ -118,11 +138,21 @@ int snd_async_del_handler(snd_async_handler_t *handler)
 	return err;
 }
 
+/**
+ * \brief Get file descriptor assigned to async handler
+ * \param handler Async handler
+ * \result file descriptor if success, otherwise a negative error code
+ */
 int snd_async_handler_get_fd(snd_async_handler_t *handler)
 {
 	return handler->fd;
 }
 
+/**
+ * \brief Get private data assigned to async handler
+ * \param handler Async handler
+ * \result private data if success, otherwise a negative error code
+ */
 void *snd_async_handler_get_callback_private(snd_async_handler_t *handler)
 {
 	return handler->private_data;
diff --git a/src/conf.c b/src/conf.c
index 1d62ab31..b5bde9cc 100644
--- a/src/conf.c
+++ b/src/conf.c
@@ -2502,7 +2502,14 @@ static int _snd_config_evaluate(snd_config_t *src,
 	return 1;
 }
 
-
+/**
+ * \brief Evaluate a config node in runtime
+ * \param config source configuration node
+ * \param root root of the source configuration
+ * \param private_data private data for runtime evaluation
+ * \param result result configuration node
+ * \return zero if success, otherwise a negative error code
+ */
 int snd_config_evaluate(snd_config_t *config, snd_config_t *root,
 		        void *private_data, snd_config_t **result)
 {
diff --git a/src/control/cards.c b/src/control/cards.c
index ece0a023..b03a92c6 100644
--- a/src/control/cards.c
+++ b/src/control/cards.c
@@ -1,3 +1,8 @@
+/**
+ * \file control/cards.c
+ * \author Jaroslav Kysela <perex@suse.cz>
+ * \date 1998-2001
+ */
 /*
  *  Control Interface - main file
  *  Copyright (c) 1998 by Jaroslav Kysela <perex@suse.cz>
@@ -28,9 +33,16 @@
 #include <sys/ioctl.h>
 #include "control_local.h"
 
+#ifndef DOC_HIDDEN
 #define SND_FILE_CONTROL	"/dev/snd/controlC%i"
 #define SND_FILE_LOAD		"/dev/aloadC%i"
+#endif
 
+/**
+ * \brief Try to load the driver for a card.
+ * \param card Card number.
+ * \return 1 if driver is present, zero if driver is not present
+ */
 int snd_card_load(int card)
 {
 	int open_dev;
@@ -47,9 +59,19 @@ int snd_card_load(int card)
 		close (open_dev);
 		return 0;
 	}
-	return open_dev;
+	return open_dev ? 1 : 0;
 }
 
+/**
+ * \brief Try to determine the next card.
+ * \param rcard pointer to card number
+ * \result zero if success, otherwise a negative error code
+ *
+ * Tries to determine the next card from given card number.
+ * If card number is -1, then the first available card is
+ * returned. If the result card number is -1, no more cards
+ * are available.
+ */
 int snd_card_next(int *rcard)
 {
 	int card;
@@ -68,6 +90,14 @@ int snd_card_next(int *rcard)
 	return 0;
 }
 
+/**
+ * \brief Convert card string to an integer value.
+ * \param string String containing card identifier
+ * \return zero if success, otherwise a negative error code
+ *
+ * The accepted format is an integer value in ASCII representation
+ * or the card identifier (snd_id parameter for soundcard drivers).
+ */
 int snd_card_get_index(const char *string)
 {
 	int card;
@@ -101,6 +131,12 @@ int snd_card_get_index(const char *string)
 	return -ENODEV;
 }
 
+/**
+ * \brief Obtain the card name.
+ * \param card Card number
+ * \param name Result - card name corresponding to card number
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_card_get_name(int card, char **name)
 {
 	snd_ctl_t *handle;
@@ -122,6 +158,12 @@ int snd_card_get_name(int card, char **name)
 	return 0;
 }
 
+/**
+ * \brief Obtain the card long name.
+ * \param card Card number
+ * \param name Result - card long name corresponding to card number
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_card_get_longname(int card, char **name)
 {
 	snd_ctl_t *handle;
diff --git a/src/control/setup.c b/src/control/setup.c
index aeb66a6c..e7acc9a9 100644
--- a/src/control/setup.c
+++ b/src/control/setup.c
@@ -72,6 +72,11 @@ static int free_elems(snd_sctl_t *h)
 	return err;
 }
 
+/**
+ * \brief Install given values to control elements
+ * \param h Setup control handle
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_sctl_install(snd_sctl_t *h)
 {
 	struct list_head *pos;
@@ -165,6 +170,11 @@ int snd_sctl_install(snd_sctl_t *h)
 	return 0;
 }
 
+/**
+ * \brief Remove (restore) previous values from control elements
+ * \param h Setup control handle
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_sctl_remove(snd_sctl_t *h)
 {
 	struct list_head *pos;
@@ -556,6 +566,15 @@ static int add_elem(snd_sctl_t *h, snd_config_t *_conf, void *private_data)
 	return err;
 }
 
+/**
+ * \brief Build setup control handle
+ * \param sctl Result - setup control handle
+ * \param handle Master control handle
+ * \param conf Setup configuration
+ * \param private_data Private data for runtime evaluation
+ * \param mode Build mode - SND_SCTL_xxxx
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_sctl_build(snd_sctl_t **sctl, snd_ctl_t *handle, snd_config_t *conf, void *private_data, int mode)
 {
 	snd_sctl_t *h;
@@ -589,6 +608,11 @@ int snd_sctl_build(snd_sctl_t **sctl, snd_ctl_t *handle, snd_config_t *conf, voi
 	return 0;
 }
 
+/**
+ * \brief Free setup control handle
+ * \param sctl Setup control handle
+ * \result zero if success, otherwise a negative error code
+ */
 int snd_sctl_free(snd_sctl_t *sctl)
 {
 	assert(sctl);
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index b8f25648..d8deac90 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -3473,7 +3473,9 @@ int snd_pcm_sw_params_set_start_mode(snd_pcm_t *pcm, snd_pcm_sw_params_t *params
 	return 0;
 }
 
+#ifndef DOC_HIDDEN
 link_warning(snd_pcm_sw_params_set_start_mode, "Warning: start_mode is deprecated, consider to use start_threshold");
+#endif
 
 /**
  * \brief (DEPRECATED) Get start mode from a software configuration container
@@ -3487,8 +3489,9 @@ snd_pcm_start_t snd_pcm_sw_params_get_start_mode(const snd_pcm_sw_params_t *para
 	return params->start_threshold > 1024 * 1024 ? SND_PCM_START_EXPLICIT : SND_PCM_START_DATA;
 }
 
+#ifndef DOC_HIDDEN
 link_warning(snd_pcm_sw_params_get_start_mode, "Warning: start_mode is deprecated, consider to use start_threshold");
-
+#endif
 
 /**
  * \brief (DEPRECATED) Set xrun mode inside a software configuration container
@@ -3514,7 +3517,9 @@ int snd_pcm_sw_params_set_xrun_mode(snd_pcm_t *pcm ATTRIBUTE_UNUSED, snd_pcm_sw_
 	return 0;
 }
 
+#ifndef DOC_HIDDEN
 link_warning(snd_pcm_sw_params_set_xrun_mode, "Warning: xrun_mode is deprecated, consider to use stop_threshold");
+#endif
 
 /**
  * \brief (DEPRECATED) Get xrun mode from a software configuration container
@@ -3528,7 +3533,9 @@ snd_pcm_xrun_t snd_pcm_sw_params_get_xrun_mode(const snd_pcm_sw_params_t *params
 	return params->stop_threshold > 1024 * 1024 ? SND_PCM_XRUN_NONE : SND_PCM_XRUN_STOP;
 }
 
+#ifndef DOC_HIDDEN
 link_warning(snd_pcm_sw_params_get_xrun_mode, "Warning: xrun_mode is deprecated, consider to use stop_threshold");
+#endif
 
 /**
  * \brief Set timestamp mode inside a software configuration container
diff --git a/src/seq/seq.c b/src/seq/seq.c
index 6e0b14e9..a759d258 100644
--- a/src/seq/seq.c
+++ b/src/seq/seq.c
@@ -1973,7 +1973,7 @@ int snd_seq_get_queue_usage(snd_seq_t *seq, int q)
 	return info.used;
 }
 
-/*
+/**
  * \brief Set the queue usage flag to the client
  * \param seq sequencer handle
  * \param q queue id
diff --git a/src/seq/seq_event.c b/src/seq/seq_event.c
index d50f4420..17cd6008 100644
--- a/src/seq/seq_event.c
+++ b/src/seq/seq_event.c
@@ -6,8 +6,11 @@
 
 #include "../../include/asoundlib.h"
 
+#ifndef DOC_HIDDEN
 #define FIXED_EV(x)	(_SND_SEQ_TYPE(SND_SEQ_EVFLG_FIXED) | _SND_SEQ_TYPE(x))
+#endif
 
+/** Event types conversion array */
 const unsigned int snd_seq_event_types[256] = {
 	[SND_SEQ_EVENT_SYSTEM ... SND_SEQ_EVENT_RESULT]
 	= FIXED_EV(SND_SEQ_EVFLG_RESULT),
diff --git a/src/seq/seq_midi_event.c b/src/seq/seq_midi_event.c
index 9df1c841..125aff9f 100644
--- a/src/seq/seq_midi_event.c
+++ b/src/seq/seq_midi_event.c
@@ -120,7 +120,9 @@ static struct extra_event_list_t {
 	/*{SND_SEQ_EVENT_REGPARAM, extra_decode_rpn},*/
 };
 
+#ifndef DOC_HIDDEN
 #define numberof(ary)	(sizeof(ary)/sizeof(ary[0]))
+#endif
 
 /**
  * \brief Initialize MIDI event parser
diff --git a/src/seq/seqmid.c b/src/seq/seqmid.c
index a3bf89e5..d6482917 100644
--- a/src/seq/seqmid.c
+++ b/src/seq/seqmid.c
@@ -345,7 +345,6 @@ int snd_seq_parse_address(snd_seq_t *seq, snd_seq_addr_t *addr, const char *arg)
 	} else {
 		/* convert from the name */
 		snd_seq_client_info_t cinfo;
-		int len;
 
 		*p = 0;
 		if (len <= 0)