More documentation enhancements / removal of non-existent functions.

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;

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)
 {

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;

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);

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

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

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),

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

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)