Fix doxygen documents

Fix the warnings of doxygen parsing.
Add some missing documentation.

doc/doxygen.cfg

@@ -35,6 +35,9 @@ INPUT            = index.doxygen \
 		   ../src/output.c \
 		   ../src/conf.c \
 		   ../src/confmisc.c \
+		   ../src/names.c \
+		   ../src/shmarea.c \
+		   ../src/userfile.c \
 		   ../src/control \
 		   ../src/mixer \
 		   ../src/pcm/pcm.c \
@@ -59,7 +62,6 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_dmix.c \
 		   ../src/pcm/pcm_dshare.c \
 		   ../src/pcm/pcm_dsnoop.c \
-		   ../src/pcm/pcm_direct.c \
 		   ../src/pcm/pcm_meter.c \
 		   ../src/pcm/pcm_ladspa.c \
 		   ../src/pcm/pcm_asym.c \
@@ -68,6 +70,7 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_extplug.c \
 		   ../src/pcm/pcm_ioplug.c \
 		   ../src/pcm/pcm_misc.c \
+		   ../src/pcm/pcm_simple.c \
 		   ../src/rawmidi \
 		   ../src/timer \
 		   ../src/hwdep \

include/conf.h

@@ -172,12 +172,18 @@ int snd_config_get_ctl_iface(const snd_config_t *conf);
 
 /* Names functions */
 
+/**
+ * Device-name list element
+ */
 typedef struct snd_devname snd_devname_t;
 
+/**
+ * Device-name list element (definition)
+ */
 struct snd_devname {
-	char *name;
+	char *name;	/**< Device name string */
-	char *comment;
+	char *comment;	/**< Comments */
-	snd_devname_t *next;
+	snd_devname_t *next;	/**< Next pointer */
 };
 
 int snd_names_list(const char *interface, snd_devname_t **list);

include/control.h

@@ -368,8 +368,8 @@ void snd_ctl_elem_info_set_subdevice(snd_ctl_elem_info_t *obj, unsigned int val)
 void snd_ctl_elem_info_set_name(snd_ctl_elem_info_t *obj, const char *val);
 void snd_ctl_elem_info_set_index(snd_ctl_elem_info_t *obj, unsigned int val);
 
-int snd_ctl_elem_add_integer(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long imin, long imax, long istep);;
+int snd_ctl_elem_add_integer(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long imin, long imax, long istep);
-int snd_ctl_elem_add_integer64(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long long imin, long long imax, long long istep);;
+int snd_ctl_elem_add_integer64(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long long imin, long long imax, long long istep);
 int snd_ctl_elem_add_boolean(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count);
 int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id);
 int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id);

include/seqmid.h

@@ -51,7 +51,7 @@ extern "C" {
 /**
  * \brief set the tag for given event
  * \param ev event record
- * \param tag event tag
+ * \param t event tag
  *
  * This macro sets the tag to the given event record.
  */
@@ -195,8 +195,8 @@ extern "C" {
 /**
  * \brief set varusr data
  * \param ev event instance
- * \param len length of the external data
+ * \param datalen length of the external data
- * \param ptr pointer of the external data
+ * \param dataptr pointer of the external data
  *
  * Sets the event length mode as variable user-space data and stores the data.
  *

include/timer.h

@@ -100,9 +100,9 @@ typedef struct _snd_timer_read {
 
 /** timer tstamp + event read structure */
 typedef struct _snd_timer_tread {
-	snd_timer_event_t event;
+	snd_timer_event_t event;	/**< Timer event */
-	snd_htimestamp_t tstamp;
+	snd_htimestamp_t tstamp;	/**< Time stamp of each event */
-	unsigned int val;
+	unsigned int val;		/**< Event value */
 } snd_timer_tread_t;
 
 /** global timer - system */

src/conf.c

@@ -290,7 +290,7 @@ syntax.<P>
 
 \section confarg_define Defining arguments
 
-Arguments are defined using the id (key) \c @args and array values containing
+Arguments are defined using the id (key) \c \@args and array values containing
 the string names of the arguments:
 
 \code
@@ -300,7 +300,7 @@ the string names of the arguments:
 
 \section confarg_type Defining argument types and default values
 
-An argument's type is specified with the id (key) \c @args and the argument
+An argument's type is specified with the id (key) \c \@args and the argument
 name. The type and the default value are specified in the compound block:
 
 \code
@@ -362,7 +362,7 @@ pcm.demo {
 <P>The ALSA library can modify the configuration at runtime.
 Several built-in functions are available.</P>
 
-<P>A function is defined with the id \c @func and the function name. All other
+<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
 library and function from this compound configuration are used, otherwise
@@ -382,7 +382,7 @@ func.remove_first_char {
 
 <P>The hook extension in the ALSA library allows expansion of configuration
 nodes at run-time. The existence of a hook is determined by the
-presence of a @hooks compound node.</P>
+presence of a \@hooks compound node.</P>
 
 <P>This example defines a hook which loads two configuration files at the
 beginning:</P>
@@ -2587,6 +2587,7 @@ int snd_config_search_alias_hooks(snd_config_t *config,
  */
 snd_config_t *snd_config = NULL;
 
+#ifndef DOC_HIDDEN
 struct finfo {
 	char *name;
 	dev_t dev;
@@ -2598,6 +2599,7 @@ struct _snd_config_update {
 	unsigned int count;
 	struct finfo *finfo;
 };
+#endif /* DOC_HIDDEN */
 
 static snd_config_update_t *snd_config_global_update = NULL;
 
@@ -2904,8 +2906,8 @@ SND_DLSYM_BUILD_VERSION(snd_config_hook_load_for_all_cards, SND_CONFIG_DLSYM_VER
 
 /** 
  * \brief Updates a configuration tree by rereading the configuration files (if needed).
- * \param top Address of the handle to the top level node.
+ * \param _top Address of the handle to the top level node.
- * \param update Address of a pointer to private update information.
+ * \param _update Address of a pointer to private update information.
  * \param cfgs A list of configuration file names, delimited with ':'.
  *             If \p cfgs is set to \c NULL, the default global configuration
  *             file is used ("/usr/share/alsa/alsa.conf").
@@ -3959,7 +3961,7 @@ int snd_config_expand(snd_config_t *config, snd_config_t *root, const char *args
  * \brief Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments.
  * \param config Handle to the configuration (sub)tree to search.
  * \param base Implicit key base, or \c NULL for none.
- * \param key Key suffix.
+ * \param name Key suffix.
  * \param result The function puts the handle to the expanded found node at
  *               the address specified by \p result.
  * \return Zero if successful, otherwise a negative error code.

src/control/control.c

@@ -406,7 +406,7 @@ int snd_ctl_elem_write(snd_ctl_t *ctl, snd_ctl_elem_value_t *control)
 /**
  * \brief Lock CTL element
  * \param ctl CTL handle
- * \param control CTL element id pointer
+ * \param id CTL element id pointer
  * \return 0 on success otherwise a negative error code
  */
 int snd_ctl_elem_lock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
@@ -418,7 +418,7 @@ int snd_ctl_elem_lock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
 /**
  * \brief Unlock CTL element
  * \param ctl CTL handle
- * \param control CTL element id pointer
+ * \param id CTL element id pointer
  * \return 0 on success otherwise a negative error code
  */
 int snd_ctl_elem_unlock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
@@ -998,7 +998,7 @@ int snd_ctl_elem_id_malloc(snd_ctl_elem_id_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_elem_id_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_elem_id_free(snd_ctl_elem_id_t *obj)
 {
@@ -1182,7 +1182,7 @@ int snd_ctl_card_info_malloc(snd_ctl_card_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_card_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_card_info_free(snd_ctl_card_info_t *obj)
 {
@@ -1311,7 +1311,7 @@ int snd_ctl_event_malloc(snd_ctl_event_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_event_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_event_free(snd_ctl_event_t *obj)
 {
@@ -1374,7 +1374,7 @@ int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_elem_list_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj)
 {
@@ -1550,7 +1550,7 @@ int snd_ctl_elem_info_malloc(snd_ctl_elem_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_elem_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_elem_info_free(snd_ctl_elem_info_t *obj)
 {
@@ -1832,6 +1832,7 @@ use_default_symbol_version(__snd_ctl_elem_info_get_dimensions, snd_ctl_elem_info
 /**
  * \brief Get specified of dimension width for given element
  * \param obj CTL element id/info
+ * \param idx The dimension index
  * \return zero value if no dimension width is defined, otherwise positive value with with of specified dimension
  */
 #ifndef DOXYGEN
@@ -2028,7 +2029,7 @@ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_ctl_elem_value_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
 {
@@ -2336,7 +2337,7 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un
 
 /**
  * \brief Set CTL element #SND_CTL_ELEM_TYPE_BYTES value
- * \param ctl CTL handle
+ * \param obj CTL handle
  * \param data Bytes value
  * \param size Size in bytes
  */
@@ -2364,7 +2365,7 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
 /**
  * \brief Get value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value 
  * \param obj CTL element id/value
- * \param Pointer to returned CTL element value
+ * \param ptr Pointer to returned CTL element value
  */ 
 void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr)
 {
@@ -2375,7 +2376,7 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9
 /**
  * \brief Set value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value 
  * \param obj CTL element id/value
- * \param Pointer to CTL element value
+ * \param ptr Pointer to CTL element value
  */ 
 void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr)
 {

src/control/control_hw.c

@@ -38,6 +38,7 @@ const char *_snd_module_control_hw = "";
 #define F_SETSIG 10
 #endif
 
+#ifndef DOC_HIDDEN
 #define SNDRV_FILE_CONTROL	"/dev/snd/controlC%i"
 #define SNDRV_CTL_VERSION_MAX	SNDRV_PROTOCOL_VERSION(2, 0, 3)
 
@@ -45,6 +46,7 @@ typedef struct {
 	int card;
 	int fd;
 } snd_ctl_hw_t;
+#endif /* DOC_HIDDEN */
 
 static int snd_ctl_hw_close(snd_ctl_t *handle)
 {

src/control/control_shm.c

@@ -40,10 +40,12 @@
 const char *_snd_module_control_shm = "";
 #endif
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	int socket;
 	volatile snd_ctl_shm_ctrl_t *ctrl;
 } snd_ctl_shm_t;
+#endif
 
 static int snd_ctl_shm_action(snd_ctl_t *ctl)
 {

src/control/hcontrol.c

@@ -187,7 +187,7 @@ int snd_hctl_poll_descriptors(snd_hctl_t *hctl, struct pollfd *pfds, unsigned in
 
 /**
  * \brief get returned events from poll descriptors
- * \param ctl HCTL handle
+ * \param hctl HCTL handle
  * \param pfds array of poll descriptors
  * \param nfds count of poll descriptors
  * \param revents returned events

src/control/setup.c

@@ -37,6 +37,7 @@
 #include <ctype.h>
 #include "local.h"
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	unsigned int lock: 1;
 	unsigned int preserve: 1;
@@ -53,6 +54,7 @@ struct _snd_sctl {
 	snd_ctl_t *ctl;
 	struct list_head elems;
 };
+#endif /* DOC_HIDDEN */
 
 static int free_elems(snd_sctl_t *h)
 {

src/dlmisc.c

@@ -151,6 +151,7 @@ void *snd_dlsym(void *handle, const char *name, const char *version)
  * FIXME: add reference counter and proper locking
  */
 
+#ifndef DOC_HIDDEN
 struct dlobj_cache {
 	const char *name;
 	void *obj;
@@ -211,3 +212,4 @@ void snd_dlobj_cache_cleanup(void)
 		free(c);
 	}
 }
+#endif

src/error.c

@@ -139,6 +139,9 @@ static void snd_err_msg_default(const char *file, int line, const char *function
 		assert(0);
 }
 
+/**
+ * The ALSA error message handler
+ */
 snd_lib_error_handler_t snd_err_msg = snd_err_msg_default;
 
 #endif

src/hwdep/hwdep.c

@@ -181,6 +181,7 @@ int snd_hwdep_open(snd_hwdep_t **hwdep, const char *name, int mode)
  * \param hwdep Returned handle (NULL if not wanted)
  * \param name ASCII identifier of the HwDep handle
  * \param mode Open mode
+ * \param lconf The local configuration tree
  * \return 0 on success otherwise a negative error code
  *
  * Opens a new connection to the HwDep interface specified with
@@ -329,7 +330,7 @@ size_t snd_hwdep_info_sizeof()
 
 /**
  * \brief allocate a new snd_hwdep_info_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_hwdep_info_t structure using the standard
@@ -370,7 +371,7 @@ void snd_hwdep_info_copy(snd_hwdep_info_t *dst, const snd_hwdep_info_t *src)
 
 /**
  * \brief get hwdep card number
- * \param info pointer to a snd_hwdep_info_t structure
+ * \param obj pointer to a snd_hwdep_info_t structure
  * \return hwdep card number
  */
 int snd_hwdep_info_get_card(const snd_hwdep_info_t *obj)
@@ -392,7 +393,7 @@ unsigned int snd_hwdep_info_get_device(const snd_hwdep_info_t *info)
 
 /**
  * \brief get hwdep driver identifier
- * \param info pointer to a snd_hwdep_info_t structure
+ * \param obj pointer to a snd_hwdep_info_t structure
  * \return hwdep driver identifier
  */
 const char *snd_hwdep_info_get_id(const snd_hwdep_info_t *obj)
@@ -403,7 +404,7 @@ const char *snd_hwdep_info_get_id(const snd_hwdep_info_t *obj)
 
 /**
  * \brief get hwdep driver name
- * \param info pointer to a snd_hwdep_info_t structure
+ * \param obj pointer to a snd_hwdep_info_t structure
  * \return hwdep driver name
  */
 const char *snd_hwdep_info_get_name(const snd_hwdep_info_t *obj)
@@ -414,7 +415,7 @@ const char *snd_hwdep_info_get_name(const snd_hwdep_info_t *obj)
 
 /**
  * \brief get hwdep protocol interface
- * \param info pointer to a snd_hwdep_info_t structure
+ * \param obj pointer to a snd_hwdep_info_t structure
  * \return hwdep protocol interface
  */
 snd_hwdep_iface_t snd_hwdep_info_get_iface(const snd_hwdep_info_t *obj)
@@ -425,7 +426,7 @@ snd_hwdep_iface_t snd_hwdep_info_get_iface(const snd_hwdep_info_t *obj)
 
 /**
  * \brief set hwdep device number
- * \param info pointer to a snd_hwdep_info_t structure
+ * \param obj pointer to a snd_hwdep_info_t structure
  * \param val hwdep device
  */
 void snd_hwdep_info_set_device(snd_hwdep_info_t *obj, unsigned int val)
@@ -525,7 +526,7 @@ size_t snd_hwdep_dsp_status_sizeof()
 
 /**
  * \brief allocate a new snd_hwdep_dsp_status_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_hwdep_dsp_status_t structure using the standard
@@ -566,7 +567,7 @@ void snd_hwdep_dsp_status_copy(snd_hwdep_dsp_status_t *dst, const snd_hwdep_dsp_
 
 /**
  * \brief get the driver version of dsp loader
- * \param info pointer to a snd_hwdep_dsp_status_t structure
+ * \param obj pointer to a snd_hwdep_dsp_status_t structure
  * \return the driver version
  */
 unsigned int snd_hwdep_dsp_status_get_version(const snd_hwdep_dsp_status_t *obj)
@@ -577,7 +578,7 @@ unsigned int snd_hwdep_dsp_status_get_version(const snd_hwdep_dsp_status_t *obj)
 
 /**
  * \brief get the driver id of dsp loader
- * \param info pointer to a snd_hwdep_dsp_status_t structure
+ * \param obj pointer to a snd_hwdep_dsp_status_t structure
  * \return the driver id string
  */
 const char *snd_hwdep_dsp_status_get_id(const snd_hwdep_dsp_status_t *obj)
@@ -588,7 +589,7 @@ const char *snd_hwdep_dsp_status_get_id(const snd_hwdep_dsp_status_t *obj)
 
 /**
  * \brief get number of dsp blocks
- * \param info pointer to a snd_hwdep_dsp_status_t structure
+ * \param obj pointer to a snd_hwdep_dsp_status_t structure
  * \return number of dsp blocks
  */
 unsigned int snd_hwdep_dsp_status_get_num_dsps(const snd_hwdep_dsp_status_t *obj)
@@ -610,7 +611,7 @@ unsigned int snd_hwdep_dsp_status_get_dsp_loaded(const snd_hwdep_dsp_status_t *i
 
 /**
  * \brief get the chip status of dsp loader
- * \param info pointer to a snd_hwdep_dsp_status_t structure
+ * \param obj pointer to a snd_hwdep_dsp_status_t structure
  * \return non-zero if all DSP blocks are loaded and the chip is ready
  */
 unsigned int snd_hwdep_dsp_status_get_chip_ready(const snd_hwdep_dsp_status_t *obj)
@@ -630,7 +631,7 @@ size_t snd_hwdep_dsp_image_sizeof()
 
 /**
  * \brief allocate a new snd_hwdep_dsp_image_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_hwdep_dsp_image_t structure using the standard
@@ -671,7 +672,7 @@ void snd_hwdep_dsp_image_copy(snd_hwdep_dsp_image_t *dst, const snd_hwdep_dsp_im
 
 /**
  * \brief get the DSP block index
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \return the index of the DSP block
  */
 unsigned int snd_hwdep_dsp_image_get_index(const snd_hwdep_dsp_image_t *obj)
@@ -682,7 +683,7 @@ unsigned int snd_hwdep_dsp_image_get_index(const snd_hwdep_dsp_image_t *obj)
 
 /**
  * \brief get the name of the DSP block
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \return the name string of the DSP block
  */
 const char *snd_hwdep_dsp_image_get_name(const snd_hwdep_dsp_image_t *obj)
@@ -693,7 +694,7 @@ const char *snd_hwdep_dsp_image_get_name(const snd_hwdep_dsp_image_t *obj)
 
 /**
  * \brief get the length of the DSP block
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \return the length of the DSP block in bytes
  */
 size_t snd_hwdep_dsp_image_get_length(const snd_hwdep_dsp_image_t *obj)
@@ -704,7 +705,7 @@ size_t snd_hwdep_dsp_image_get_length(const snd_hwdep_dsp_image_t *obj)
 
 /**
  * \brief get the image pointer of the DSP block
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \return the image pointer of the DSP block
  */
 const void *snd_hwdep_dsp_image_get_image(const snd_hwdep_dsp_image_t *obj)
@@ -715,7 +716,7 @@ const void *snd_hwdep_dsp_image_get_image(const snd_hwdep_dsp_image_t *obj)
 
 /**
  * \brief set the DSP block index
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \param index the index value to set
  */
 void snd_hwdep_dsp_image_set_index(snd_hwdep_dsp_image_t *obj, unsigned int index)
@@ -726,7 +727,7 @@ void snd_hwdep_dsp_image_set_index(snd_hwdep_dsp_image_t *obj, unsigned int inde
 
 /**
  * \brief set the name of the DSP block
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \param name the name string
  */
 void snd_hwdep_dsp_image_set_name(snd_hwdep_dsp_image_t *obj, const char *name)
@@ -738,7 +739,7 @@ void snd_hwdep_dsp_image_set_name(snd_hwdep_dsp_image_t *obj, const char *name)
 
 /**
  * \brief set the DSP block length
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \param length the length of the DSP block
  */
 void snd_hwdep_dsp_image_set_length(snd_hwdep_dsp_image_t *obj, size_t length)
@@ -749,7 +750,7 @@ void snd_hwdep_dsp_image_set_length(snd_hwdep_dsp_image_t *obj, size_t length)
 
 /**
  * \brief set the DSP block image pointer
- * \param info pointer to a snd_hwdep_dsp_image_t structure
+ * \param obj pointer to a snd_hwdep_dsp_image_t structure
  * \param image the DSP image pointer
  */
 void snd_hwdep_dsp_image_set_image(snd_hwdep_dsp_image_t *obj, void *image)

src/input.c

@@ -89,7 +89,7 @@ int snd_input_scanf(snd_input_t *input, const char *format, ...)
  * \return Pointer to the buffer if successful, otherwise \c NULL.
  *
  * Like \c fgets, the returned string is zero-terminated, and contains
- * the new-line character \c '\n' if the line fits into the buffer.
+ * the new-line character \c '\\n' if the line fits into the buffer.
  */
 char *snd_input_gets(snd_input_t *input, char *str, size_t size)
 {
@@ -172,7 +172,7 @@ static snd_input_ops_t snd_input_stdio_ops = {
  *               at the address specified by \p inputp.
  * \param fp The \c FILE pointer to read from.
  *           Reading begins at the current file position.
- * \param close Close flag. Set this to 1 if #snd_input_close should close
+ * \param _close Close flag. Set this to 1 if #snd_input_close should close
  *              \p fp by calling \c fclose.
  * \return Zero if successful, otherwise a negative error code.
  */

src/instr/fm.c

@@ -34,12 +34,14 @@
 #include <linux/version.h>
 #if LINUX_VERSION_CODE == KERNEL_VERSION(2,6,9)
 #include <asm/types.h>
+#ifndef DOC_HIDDEN
 #define __le64 __u64
 #define __le32 __u32
 #define __le16 __u16
 #define __be64 __u64
 #define __be32 __u32
 #define __be16 __u16
+#endif
 #endif /* linux 2.6.9 workaround */
 #include <asm/byteorder.h>
 #include <sound/ainstr_fm.h>

src/instr/iwffff.c

@@ -35,12 +35,14 @@
 #include <linux/version.h>
 #if LINUX_VERSION_CODE == KERNEL_VERSION(2,6,9)
 #include <asm/types.h>
+#ifndef DOC_HIDDEN
 #define __le64 __u64
 #define __le32 __u32
 #define __le16 __u16
 #define __be64 __u64
 #define __be32 __u32
 #define __be16 __u16
+#endif
 #endif /* linux 2.6.9 workaround */
 #include <sound/ainstr_iw.h>
 

src/instr/simple.c

@@ -35,12 +35,14 @@
 #include <linux/version.h>
 #if LINUX_VERSION_CODE == KERNEL_VERSION(2,6,9)
 #include <asm/types.h>
+#ifndef DOC_HIDDEN
 #define __le64 __u64
 #define __le32 __u32
 #define __le16 __u16
 #define __be64 __u64
 #define __be32 __u32
 #define __be16 __u16
+#endif
 #endif /* linux 2.6.9 workaround */
 #include <asm/byteorder.h>
 #include <sound/ainstr_simple.h>

src/mixer/mixer.c

@@ -744,8 +744,8 @@ int snd_mixer_handle_events(snd_mixer_t *mixer)
 
 /**
  * \brief Set callback function for a mixer
- * \param mixer mixer handle
+ * \param obj mixer handle
- * \param callback callback function
+ * \param val callback function
  */
 void snd_mixer_set_callback(snd_mixer_t *obj, snd_mixer_callback_t val)
 {
@@ -755,8 +755,8 @@ 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 obj mixer handle
- * \param callback_private callback private value
+ * \param val callback private value
  */
 void snd_mixer_set_callback_private(snd_mixer_t *obj, void * val)
 {
@@ -766,7 +766,7 @@ void snd_mixer_set_callback_private(snd_mixer_t *obj, void * val)
 
 /**
  * \brief Get callback private value for a mixer
- * \param mixer mixer handle
+ * \param obj mixer handle
  * \return callback private value
  */
 void * snd_mixer_get_callback_private(const snd_mixer_t *obj)
@@ -777,7 +777,7 @@ void * snd_mixer_get_callback_private(const snd_mixer_t *obj)
 
 /**
  * \brief Get elements count for a mixer
- * \param mixer mixer handle
+ * \param obj mixer handle
  * \return elements count
  */
 unsigned int snd_mixer_get_count(const snd_mixer_t *obj)

src/mixer/simple.c

@@ -2035,7 +2035,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)
 {

src/names.c

@@ -39,9 +39,11 @@
 #include <locale.h>
 #include "local.h"
 
+#ifndef DOC_HIDDEN
 #define ALSA_NAMES_ENV	 "ALSA_NAMES_FILE"
 #define ALSA_NAMES_PATH1 "/etc/asound.names"
 #define ALSA_NAMES_PATH2 "~/.asoundnm"
+#endif
 
 static int names_parse(snd_config_t *top, const char *interface, snd_devname_t **list)
 {
@@ -171,6 +173,12 @@ int snd_names_list(const char *interface, snd_devname_t **list)
 	return err >= 0 ? 0 : err;
 }
 
+/**
+ * \brief Release the list of device names
+ * \param list the name list to release
+ *
+ * Releases the list of device names allocated via #snd_names_list().
+ */
 void snd_names_list_free(snd_devname_t *list)
 {
 	snd_devname_t *next;

src/output.c

@@ -181,7 +181,7 @@ static snd_output_ops_t snd_output_stdio_ops = {
  *                at the address specified by \p outputp.
  * \param fp The \c FILE pointer to write to. Characters are written
  *           to the file starting at the current file position.
- * \param close Close flag. Set this to 1 if #snd_output_close should close
+ * \param _close Close flag. Set this to 1 if #snd_output_close should close
  *              \p fp by calling \c fclose.
  * \return Zero if successful, otherwise a negative error code.
  */

src/pcm/pcm.c

@@ -1047,7 +1047,7 @@ int snd_pcm_drain(snd_pcm_t *pcm)
 /**
  * \brief Pause/resume PCM
  * \param pcm PCM handle
- * \param pause 0 = resume, 1 = pause
+ * \param enable 0 = resume, 1 = pause
  * \return 0 on success otherwise a negative error code
  *
  * Note that this function works only on the hardware which supports
@@ -1552,7 +1552,7 @@ const char *snd_pcm_stream_name(snd_pcm_stream_t stream)
 
 /**
  * \brief get name of PCM access type
- * \param access PCM access type
+ * \param acc PCM access type
  * \return ascii name of PCM access type
  */
 const char *snd_pcm_access_name(snd_pcm_access_t acc)
@@ -1615,7 +1615,7 @@ snd_pcm_format_t snd_pcm_format_value(const char* name)
 
 /**
  * \brief get name of PCM sample subformat
- * \param format PCM sample subformat
+ * \param subformat PCM sample subformat
  * \return ascii name of PCM sample subformat
  */
 const char *snd_pcm_subformat_name(snd_pcm_subformat_t subformat)
@@ -2663,7 +2663,7 @@ int snd_pcm_hw_params_dump(snd_pcm_hw_params_t *params, snd_output_t *out)
 
 /**
  * \brief Check, if hardware supports sample-resolution mmap for given configuration
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't support sample-resolution mmap
  * \retval 1 Hardware supports sample-resolution mmap
@@ -2684,7 +2684,7 @@ int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *para
 
 /**
  * \brief Check, if hardware does double buffering for start/stop for given configuration
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't do double buffering for start/stop
  * \retval 1 Hardware does double buffering for start/stop
@@ -2705,7 +2705,7 @@ int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware does double buffering for data transfers for given configuration
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't do double buffering for data transfers
  * \retval 1 Hardware does double buffering for data transfers
@@ -2726,7 +2726,7 @@ int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware does block transfers for samples for given configuration
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't block transfers
  * \retval 1 Hardware does block transfers
@@ -2747,7 +2747,7 @@ int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware supports overrange detection
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't support overrange detection
  * \retval 1 Hardware supports overrange detection
@@ -2768,7 +2768,7 @@ int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware supports pause
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't support pause
  * \retval 1 Hardware supports pause
@@ -2789,7 +2789,7 @@ int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware supports resume
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't support resume
  * \retval 1 Hardware supports resume
@@ -2810,7 +2810,7 @@ int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware does half-duplex only
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't do half-duplex
  * \retval 1 Hardware does half-duplex
@@ -2831,7 +2831,7 @@ int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware does joint-duplex (playback and capture are somewhat correlated)
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't do joint-duplex
  * \retval 1 Hardware does joint-duplex
@@ -2852,7 +2852,7 @@ int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params)
 
 /**
  * \brief Check, if hardware supports synchronized start with sample resolution
- * \param param Configuration space
+ * \param params Configuration space
  * \return Boolean value
  * \retval 0 Hardware doesn't support synchronized start
  * \retval 1 Hardware supports synchronized start
@@ -2969,7 +2969,7 @@ int snd_pcm_access_mask_malloc(snd_pcm_access_mask_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_access_mask_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_access_mask_free(snd_pcm_access_mask_t *obj)
 {
@@ -3071,7 +3071,7 @@ int snd_pcm_format_mask_malloc(snd_pcm_format_mask_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_format_mask_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_format_mask_free(snd_pcm_format_mask_t *obj)
 {
@@ -3174,7 +3174,7 @@ int snd_pcm_subformat_mask_malloc(snd_pcm_subformat_mask_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_subformat_mask_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_subformat_mask_free(snd_pcm_subformat_mask_t *obj)
 {
@@ -3277,7 +3277,7 @@ int snd_pcm_hw_params_malloc(snd_pcm_hw_params_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_hw_params_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_hw_params_free(snd_pcm_hw_params_t *obj)
 {
@@ -3359,7 +3359,7 @@ int snd_pcm_hw_params_set_access_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *para
  * \brief Restrict a configuration space to contain only its last access type
  * \param pcm PCM handle
  * \param params Configuration space
- * \param val Returned last access type
+ * \param access Returned last access type
  * \return 0 otherwise a negative error code
  */
 #ifndef DOXYGEN
@@ -3876,6 +3876,7 @@ int snd_pcm_hw_params_set_rate_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *param
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target rate / returned approximate set rate
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -3947,7 +3948,8 @@ int snd_pcm_hw_params_set_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *par
 /**
  * \brief Extract resample state from a configuration space
  * \param pcm PCM handle
- * \param *val 0 = disable, 1 = enable rate resampling
+ * \param params Configuration space
+ * \param val 0 = disable, 1 = enable rate resampling
  * \return 0 otherwise a negative error code
  */
 int snd_pcm_hw_params_get_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
@@ -3977,7 +3979,8 @@ int snd_pcm_hw_params_set_export_buffer(snd_pcm_t *pcm, snd_pcm_hw_params_t *par
 /**
  * \brief Extract buffer accessibility from a configuration space
  * \param pcm PCM handle
- * \param *val 0 = disable, 1 = enable exporting buffer
+ * \param params Configuration space
+ * \param val 0 = disable, 1 = enable exporting buffer
  * \return 0 otherwise a negative error code
  */
 int snd_pcm_hw_params_get_export_buffer(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
@@ -4124,6 +4127,7 @@ int snd_pcm_hw_params_set_period_time_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target period duration in us / returned chosen approximate target period duration
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -4160,10 +4164,9 @@ int snd_pcm_hw_params_set_period_time_first(snd_pcm_t *pcm, snd_pcm_hw_params_t
  * \brief Restrict a configuration space to contain only its maximum period time
  * \param pcm PCM handle
  * \param params Configuration space
+ * \param val Returned maximum approximate period time
  * \param dir Sub unit direction
  * \return approximate period duration in us
- *
- * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_pcm_hw_params_set_period_time_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
@@ -4336,6 +4339,7 @@ int snd_pcm_hw_params_set_period_size_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target period size in frames / returned chosen approximate target period size
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -4547,6 +4551,7 @@ int snd_pcm_hw_params_set_periods_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *pa
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target periods per buffer / returned chosen approximate target periods per buffer
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -4613,7 +4618,6 @@ int snd_pcm_hw_params_set_periods_integer(snd_pcm_t *pcm, snd_pcm_hw_params_t *p
 /**
  * \brief Extract buffer time from a configuration space
  * \param params Configuration space
- * \param approximate buffer duration in us
  * \param val Returned buffer time in us
  * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if not exactly one is present
@@ -4747,6 +4751,7 @@ int snd_pcm_hw_params_set_buffer_time_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target buffer duration in us / returned chosen approximate target buffer duration
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -4822,10 +4827,7 @@ int snd_pcm_hw_params_get_buffer_size(const snd_pcm_hw_params_t *params, snd_pcm
  * \brief Extract minimum buffer size from a configuration space
  * \param params Configuration space
  * \param val Returned approximate minimum buffer size in frames
- * \param dir Sub unit direction
  * \return 0 otherwise a negative error code
- *
- * Exact value is <,=,> the returned one following dir (-1,0,1)
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_pcm_hw_params_get_buffer_size_min)(const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
@@ -4844,7 +4846,6 @@ int snd_pcm_hw_params_get_buffer_size_min(const snd_pcm_hw_params_t *params, snd
  * \brief Extract maximum buffer size from a configuration space
  * \param params Configuration space
  * \param val Returned approximate maximum buffer size in frames
- * \param dir Sub unit direction
  * \return 0 otherwise a negative error code
  *
  * Exact value is <,=,> the returned one following dir (-1,0,1)
@@ -4867,7 +4868,6 @@ int snd_pcm_hw_params_get_buffer_size_max(const snd_pcm_hw_params_t *params, snd
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val buffer size in frames
- * \param dir Sub unit direction
  * \return 0 if available a negative error code otherwise
  *
  * Wanted exact value is <,=,> val following dir (-1,0,1)
@@ -4896,10 +4896,7 @@ int snd_pcm_hw_params_set_buffer_size(snd_pcm_t *pcm, snd_pcm_hw_params_t *param
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate minimum buffer size in frames (on return filled with actual minimum)
- * \param dir Sub unit direction (on return filled with actual direction)
  * \return 0 otherwise a negative error code if configuration space would become empty
- *
- * Wanted/actual exact minimum is <,=,> val following dir (-1,0,1)
  */
 int snd_pcm_hw_params_set_buffer_size_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
 {
@@ -4915,10 +4912,7 @@ int snd_pcm_hw_params_set_buffer_size_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *p
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate maximum buffer size in frames (on return filled with actual maximum)
- * \param dir Sub unit direction (on return filled with actual direction)
  * \return 0 otherwise a negative error code if configuration space would become empty
- *
- * Wanted/actual exact minimum is <,=,> val following dir (-1,0,1)
  */
 int snd_pcm_hw_params_set_buffer_size_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
 {
@@ -4934,12 +4928,8 @@ int snd_pcm_hw_params_set_buffer_size_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *p
  * \param pcm PCM handle
  * \param params Configuration space
  * \param min approximate minimum buffer size in frames (on return filled with actual minimum)
- * \param mindir Sub unit direction for minimum (on return filled with actual direction)
  * \param max approximate maximum buffer size in frames (on return filled with actual maximum)
- * \param maxdir Sub unit direction for maximum (on return filled with actual direction)
  * \return 0 otherwise a negative error code if configuration space would become empty
- *
- * Wanted/actual exact min/max is <,=,> val following dir (-1,0,1)
  */
 int snd_pcm_hw_params_set_buffer_size_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_uframes_t *min, snd_pcm_uframes_t *max)
 {
@@ -4957,8 +4947,6 @@ int snd_pcm_hw_params_set_buffer_size_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t
  * \param params Configuration space
  * \param val approximate target buffer size in frames / returned chosen approximate target buffer size in frames
  * \return 0 otherwise a negative error code if configuration space is empty
- *
- * target/chosen exact value is <,=,> val following dir (-1,0,1)
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_pcm_hw_params_set_buffer_size_near)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
@@ -5150,6 +5138,7 @@ int snd_pcm_hw_params_set_tick_time_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *
  * \param pcm PCM handle
  * \param params Configuration space
  * \param val approximate target tick duration in us / returned chosen approximate target tick duration in us
+ * \param dir Sub unit direction
  * \return 0 otherwise a negative error code if configuration space is empty
  *
  * target/chosen exact value is <,=,> val following dir (-1,0,1)
@@ -5302,7 +5291,7 @@ int snd_pcm_sw_params_malloc(snd_pcm_sw_params_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_sw_params_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_sw_params_free(snd_pcm_sw_params_t *obj)
 {
@@ -5320,7 +5309,7 @@ void snd_pcm_sw_params_copy(snd_pcm_sw_params_t *dst, const snd_pcm_sw_params_t
 	*dst = *src;
 }
 
-/*
+/**
  * \brief Get boundary for ring pointers from a software configuration container
  * \param params Software configuration container
  * \param val Returned boundary in frames
@@ -5570,7 +5559,7 @@ int snd_pcm_sw_params_set_xfer_align(snd_pcm_t *pcm, snd_pcm_sw_params_t *params
  * \brief Get xfer align from a software configuration container
  * \param params Software configuration container
  * \param val returned chunk size (frames are attempted to be transferred in chunks)
- * \param 0 otherwise a negative error code
+ * \return 0 otherwise a negative error code
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_pcm_sw_params_get_xfer_align)(const snd_pcm_sw_params_t *params, snd_pcm_uframes_t *val)
@@ -5800,7 +5789,7 @@ int snd_pcm_status_malloc(snd_pcm_status_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_status_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_status_free(snd_pcm_status_t *obj)
 {
@@ -5820,6 +5809,7 @@ void snd_pcm_status_copy(snd_pcm_status_t *dst, const snd_pcm_status_t *src)
 
 /** 
  * \brief Get state from a PCM status container (see #snd_pcm_state)
+ * \param obj #snd_pcm_status_t pointer
  * \return PCM state
  */
 snd_pcm_state_t snd_pcm_status_get_state(const snd_pcm_status_t *obj)
@@ -5830,6 +5820,7 @@ snd_pcm_state_t snd_pcm_status_get_state(const snd_pcm_status_t *obj)
 
 /** 
  * \brief Get trigger timestamp from a PCM status container
+ * \param obj #snd_pcm_status_t pointer
  * \param ptr Pointer to returned timestamp
  */
 void snd_pcm_status_get_trigger_tstamp(const snd_pcm_status_t *obj, snd_timestamp_t *ptr)
@@ -5841,6 +5832,7 @@ void snd_pcm_status_get_trigger_tstamp(const snd_pcm_status_t *obj, snd_timestam
 
 /** 
  * \brief Get trigger hi-res timestamp from a PCM status container
+ * \param obj #snd_pcm_status_t pointer
  * \param ptr Pointer to returned timestamp
  */
 #ifndef DOXYGEN
@@ -5856,6 +5848,7 @@ use_default_symbol_version(__snd_pcm_status_get_trigger_htstamp, snd_pcm_status_
 
 /** 
  * \brief Get "now" timestamp from a PCM status container
+ * \param obj #snd_pcm_status_t pointer
  * \param ptr Pointer to returned timestamp
  */
 void snd_pcm_status_get_tstamp(const snd_pcm_status_t *obj, snd_timestamp_t *ptr)
@@ -5867,6 +5860,7 @@ void snd_pcm_status_get_tstamp(const snd_pcm_status_t *obj, snd_timestamp_t *ptr
 
 /** 
  * \brief Get "now" hi-res timestamp from a PCM status container
+ * \param obj pointer to #snd_pcm_status_t
  * \param ptr Pointer to returned timestamp
  */
 #ifndef DOXYGEN
@@ -5951,7 +5945,7 @@ int snd_pcm_info_malloc(snd_pcm_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_pcm_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_pcm_info_free(snd_pcm_info_t *obj)
 {
@@ -6186,7 +6180,7 @@ int snd_pcm_mmap_begin(snd_pcm_t *pcm,
  * \brief Application has completed the access to area requested with #snd_pcm_mmap_begin
  * \param pcm PCM handle
  * \param offset area offset in area steps (== frames)
- * \param size area portion size in frames
+ * \param frames area portion size in frames
  * \return count of transferred frames otherwise a negative error code
  *
  * You should pass this function the offset value that

src/pcm/pcm_direct.c

@@ -1,10 +1,3 @@
-/**
- * \file pcm/pcm_direct.c
- * \ingroup PCM_Plugins
- * \brief PCM Direct Stream Mixing (dmix) Plugin Interface
- * \author Jaroslav Kysela <perex@suse.cz>
- * \date 2003
- */
 /*
  *  PCM - Direct Stream Mixing
  *  Copyright (c) 2003 by Jaroslav Kysela <perex@suse.cz>

src/pcm/pcm_direct.h

@@ -1,10 +1,3 @@
-/**
- * \file pcm/pcm_dmix.c
- * \ingroup PCM_Plugins
- * \brief PCM Direct Stream Mixing (dmix) Plugin Interface
- * \author Jaroslav Kysela <perex@suse.cz>
- * \date 2003
- */
 /*
  *  PCM - Direct Stream Mixing
  *  Copyright (c) 2003 by Jaroslav Kysela <perex@suse.cz>

src/pcm/pcm_dmix.c

@@ -49,8 +49,10 @@
 const char *_snd_module_pcm_dmix = "";
 #endif
 
+#ifndef DOC_HIDDEN
 /* start is pending - this state happens when rate plugin does a delayed commit */
 #define STATE_RUN_PENDING	1024
+#endif
 
 /*
  *
@@ -209,6 +211,7 @@ static void mix_areas(snd_pcm_direct_t *dmix,
  * if no concurrent access is allowed in the mixing routines, we need to protect
  * the area via semaphore
  */
+#ifndef DOC_HIDDEN
 #ifdef NO_CONCURRENT_ACCESS
 #define dmix_down_sem(dmix) snd_pcm_direct_semaphore_down(dmix, DIRECT_IPC_SEM_CLIENT)
 #define dmix_up_sem(dmix) snd_pcm_direct_semaphore_up(dmix, DIRECT_IPC_SEM_CLIENT)
@@ -216,6 +219,7 @@ static void mix_areas(snd_pcm_direct_t *dmix,
 #define dmix_down_sem(dmix)
 #define dmix_up_sem(dmix)
 #endif
+#endif
 
 /*
  *  synchronize shm ring buffer with hardware

src/pcm/pcm_dshare.c

@@ -49,8 +49,10 @@
 const char *_snd_module_pcm_dshare = "";
 #endif
 
+#ifndef DOC_HIDDEN
 /* start is pending - this state happens when rate plugin does a delayed commit */
 #define STATE_RUN_PENDING	1024
+#endif
 
 static void do_silence(snd_pcm_t *pcm)
 {
@@ -575,7 +577,7 @@ static snd_pcm_fast_ops_t snd_pcm_dshare_fast_ops = {
  * \param pcmp Returns created PCM handle
  * \param name Name of PCM
  * \param ipc_key IPC key for semaphore and shared memory
- * \param ipc_mode IPC permissions for semaphore and shared memory
+ * \param ipc_perm IPC permissions for semaphore and shared memory
  * \param params Parameters for slave
  * \param bindings Channel bindings
  * \param slowptr Slow but more precise pointer updates

src/pcm/pcm_file.c

@@ -387,6 +387,7 @@ static snd_pcm_fast_ops_t snd_pcm_file_fast_ops = {
  * \param fname Filename (or NULL if file descriptor is available)
  * \param fd File descriptor
  * \param fmt File format ("raw" is supported only)
+ * \param perm File permission
  * \param slave Slave PCM handle
  * \param close_slave When set, the slave PCM handle is closed with copy PCM
  * \retval zero on success otherwise a negative error code

src/pcm/pcm_hw.c

@@ -111,7 +111,6 @@ typedef struct {
 	((enum sndrv_pcm_state) (hw)->mmap_status->state)
 #define FAST_PCM_TSTAMP(hw) \
 	((hw)->mmap_status->tstamp)
-#endif /* DOC_HIDDEN */
 
 struct timespec snd_pcm_hw_fast_tstamp(snd_pcm_t *pcm)
 {
@@ -122,6 +121,7 @@ struct timespec snd_pcm_hw_fast_tstamp(snd_pcm_t *pcm)
 		res.tv_nsec *= 1000L;
 	return res;
 }
+#endif /* DOC_HIDDEN */
 
 static int sync_ptr1(snd_pcm_hw_t *hw, unsigned int flags)
 {
@@ -1039,6 +1039,8 @@ static snd_pcm_fast_ops_t snd_pcm_hw_fast_ops = {
  * \param pcmp Returns created PCM handle
  * \param name Name of PCM
  * \param fd File descriptor
+ * \param mmap_emulation Boolean flag for mmap emulation mode
+ * \param sync_ptr_ioctl Boolean flag for sync_ptr ioctl
  * \retval zero on success otherwise a negative error code
  * \warning Using of this function might be dangerous in the sense
  *          of compatibility reasons. The prototype might be freely

src/pcm/pcm_iec958.c

@@ -138,6 +138,7 @@ static inline int32_t iec958_to_s32(snd_pcm_iec958_t *iec, u_int32_t data)
 	return (int32_t)data;
 }
 
+#ifndef DOC_HIDDEN
 static void snd_pcm_iec958_decode(snd_pcm_iec958_t *iec,
 				  const snd_pcm_channel_area_t *dst_areas,
 				  snd_pcm_uframes_t dst_offset,
@@ -218,6 +219,7 @@ static void snd_pcm_iec958_encode(snd_pcm_iec958_t *iec,
 		}
 	}
 }
+#endif /* DOC_HIDDEN */
 
 static int snd_pcm_iec958_hw_refine_cprepare(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
@@ -434,6 +436,8 @@ static snd_pcm_ops_t snd_pcm_iec958_ops = {
  * \param sformat Slave (destination) format
  * \param slave Slave PCM handle
  * \param close_slave When set, the slave PCM handle is closed with copy PCM
+ * \param status_bits The IEC958 status bits
+ * \param preamble_vals The preamble byte values
  * \retval zero on success otherwise a negative error code
  * \warning Using of this function might be dangerous in the sense
  *          of compatibility reasons. The prototype might be freely

src/pcm/pcm_ladspa.c

@@ -1117,7 +1117,9 @@ static int snd_pcm_ladspa_build_plugins(struct list_head *list,
  * \brief Creates a new LADSPA<->ALSA Plugin
  * \param pcmp Returns created PCM handle
  * \param name Name of PCM
- * \param sformat Slave (destination) format
+ * \param ladspa_path The path for LADSPA plugins
+ * \param ladspa_pplugins The playback configuration
+ * \param ladspa_cplugins The capture configuration
  * \param slave Slave PCM handle
  * \param close_slave When set, the slave PCM handle is closed with copy PCM
  * \retval zero on success otherwise a negative error code

src/pcm/pcm_meter.c

@@ -924,7 +924,7 @@ snd_pcm_uframes_t snd_pcm_meter_get_boundary(snd_pcm_t *pcm)
 /**
  * \brief Set name of a #SND_PCM_TYPE_METER PCM scope
  * \param scope PCM meter scope
- * \param name scope name
+ * \param val scope name
  */
 void snd_pcm_scope_set_name(snd_pcm_scope_t *scope, const char *val)
 {
@@ -1147,6 +1147,7 @@ snd_pcm_scope_ops_t s16_ops = {
 
 /**
  * \brief Add a s16 pseudo scope to a #SND_PCM_TYPE_METER PCM
+ * \param pcm The pcm handle
  * \param name Scope name
  * \param scopep Pointer to newly created and added scope
  * \return 0 on success otherwise a negative error code

src/pcm/pcm_misc.c

@@ -541,7 +541,8 @@ u_int8_t snd_pcm_format_silence(snd_pcm_format_t format)
  * \brief Silence a PCM samples buffer
  * \param format Sample format
  * \param data Buffer
- * \return samples Samples count
+ * \param samples Samples count
+ * \return 0 if successful or a negative error code
  */
 int snd_pcm_format_set_silence(snd_pcm_format_t format, void *data, unsigned int samples)
 {
@@ -661,7 +662,8 @@ static int linear24_formats[3*2*2] = {
  * \param width Nominal bits per sample
  * \param pwidth Physical bit width of the format
  * \param unsignd Sign: 0 signed, 1 unsigned
- * \return big_endian Endian: 0 little endian, 1 big endian
+ * \param big_endian Endian: 0 little endian, 1 big endian
+ * \return The matching format type, or #SND_PCM_FORMAT_UNKNOWN if no match
  */
 snd_pcm_format_t snd_pcm_build_linear_format(int width, int pwidth, int unsignd, int big_endian)
 {

src/pcm/pcm_plug.c

@@ -311,12 +311,14 @@ static void snd_pcm_plug_clear(snd_pcm_t *pcm)
 	}
 }
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	snd_pcm_access_t access;
 	snd_pcm_format_t format;
 	unsigned int channels;
 	unsigned int rate;
 } snd_pcm_plug_params_t;
+#endif
 
 static int snd_pcm_plug_change_rate(snd_pcm_t *pcm, snd_pcm_t **new, snd_pcm_plug_params_t *clt, snd_pcm_plug_params_t *slv)
 {

src/pcm/pcm_rate.c

@@ -620,7 +620,7 @@ static int snd_pcm_rate_hw_free(snd_pcm_t *pcm)
 	return snd_pcm_hw_free(rate->gen.slave);
 }
 
-int snd_pcm_rate_channel_info(snd_pcm_t *pcm, snd_pcm_channel_info_t * info)
+static int snd_pcm_rate_channel_info(snd_pcm_t *pcm, snd_pcm_channel_info_t * info)
 {
 	return snd_pcm_channel_info_shm(pcm, info, -1);
 }

src/pcm/pcm_simple.c

@@ -143,6 +143,20 @@ static int set_sw_params(snd_pcm_t *pcm,
 	return 0;
 }
 
+/**
+ * \brief Set up a simple PCM
+ * \param pcm PCM handle
+ * \param rate Sample rate
+ * \param channels Number of channels
+ * \param format PCM format
+ * \param subformat PCM subformat
+ * \param latency Latency type
+ * \param access PCM acceess type
+ * \param xrun_type XRUN type
+ * \return 0 if successful, or a negative error code
+ *
+ * \warning The simple PCM API may be broken in the current release.
+ */
 int snd_spcm_init(snd_pcm_t *pcm,
 		  unsigned int rate,
 		  unsigned int channels,
@@ -182,6 +196,22 @@ int snd_spcm_init(snd_pcm_t *pcm,
 	return 0;
 }
 
+/**
+ * \brief Initialize simple PCMs in the duplex mode
+ * \param playback_pcm PCM handle for playback
+ * \param capture_pcm PCM handle for capture
+ * \param rate Sample rate
+ * \param channels Number of channels
+ * \param format PCM format
+ * \param subformat PCM subformat
+ * \param latency Latency type
+ * \param access PCM acceess type
+ * \param xrun_type XRUN type
+ * \param duplex_type Duplex mode
+ * \return 0 if successful, or a negative error code
+ *
+ * \warning The simple PCM API may be broken in the current release.
+ */
 int snd_spcm_init_duplex(snd_pcm_t *playback_pcm,
 			 snd_pcm_t *capture_pcm,
 			 unsigned int rate,
@@ -250,6 +280,16 @@ int snd_spcm_init_duplex(snd_pcm_t *playback_pcm,
 	return 0;
 }
 
+/**
+ * \brief Get the set up of simple PCM
+ * \param pcm PCM handle
+ * \param rate Pointer to store the current sample rate
+ * \param buffer_size Pointer to store the current buffer size
+ * \param period_size Pointer to store the current period size
+ * \return 0 if successful, or a negative error code
+ *
+ * \warning The simple PCM API may be broken in the current release.
+ */
 int snd_spcm_init_get_params(snd_pcm_t *pcm,
 			     unsigned int *rate,
 			     snd_pcm_uframes_t *buffer_size,

src/pcm/pcm_softvol.c

@@ -124,6 +124,7 @@ static inline int MULTI_DIV_int(int a, unsigned short b)
  * TODO: use SIMD operations
  */
 
+#ifndef DOC_HIDDEN
 #define CONVERT_AREA(TYPE) do {	\
 	unsigned int ch, fr; \
 	TYPE *src, *dst; \
@@ -174,6 +175,8 @@ static inline int MULTI_DIV_int(int a, unsigned short b)
 		break; \
 	}
 
+#endif /* DOC_HIDDEN */
+
 /* 2-channel stereo control */
 static void softvol_convert_stereo_vol(snd_pcm_softvol_t *svol,
 				       const snd_pcm_channel_area_t *dst_areas,
@@ -592,7 +595,9 @@ static snd_pcm_ops_t snd_pcm_softvol_ops = {
  * \param pcmp Returns created PCM handle
  * \param name Name of PCM
  * \param sformat Slave format
- * \param card card index of the control
+ * \param ctl_card card index of the control
+ * \param ctl_id The control element
+ * \param cchannels PCM channels
  * \param min_dB minimal dB value
  * \param resolution resolution of control
  * \param slave Slave PCM handle

src/rawmidi/rawmidi.c

@@ -422,7 +422,7 @@ int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rawmidi, struct pollfd *pfds, un
 
 /**
  * \brief get returned events from poll descriptors
- * \param pcm rawmidi RawMidi handle
+ * \param rawmidi rawmidi RawMidi handle
  * \param pfds array of poll descriptors
  * \param nfds count of poll descriptors
  * \param revents returned events
@@ -472,7 +472,7 @@ size_t snd_rawmidi_info_sizeof()
 
 /**
  * \brief allocate a new snd_rawmidi_info_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_rawmidi_params_t structure using the standard
@@ -678,7 +678,7 @@ size_t snd_rawmidi_params_sizeof()
 
 /**
  * \brief allocate the snd_rawmidi_params_t structure
- * \param ptr returned pointer
+ * \param params returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_rawmidi_params_t structure using the standard

src/rawmidi/rawmidi_hw.c

@@ -37,11 +37,13 @@ const char *_snd_module_rawmidi_hw = "";
 #define SNDRV_FILE_RAWMIDI		"/dev/snd/midiC%iD%i"
 #define SNDRV_RAWMIDI_VERSION_MAX	SNDRV_PROTOCOL_VERSION(2, 0, 0)
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	int open;
 	int fd;
 	int card, device, subdevice;
 } snd_rawmidi_hw_t;
+#endif
 
 static int snd_rawmidi_hw_close(snd_rawmidi_t *rmidi)
 {

src/rawmidi/rawmidi_virt.c

@@ -35,6 +35,7 @@ const char *_snd_module_rawmidi_virt = "";
 #endif
 
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	int open;
 
@@ -52,6 +53,7 @@ typedef struct {
 	snd_seq_event_t out_event;
 	int pending;
 } snd_rawmidi_virtual_t;
+#endif
 
 static int snd_rawmidi_virtual_close(snd_rawmidi_t *rmidi)
 {

src/seq/seq.c

@@ -235,7 +235,7 @@ The queue field is the queue id for scheduling.
 The source and dest fields are source and destination addresses.
 The data field is a union of event data.
 
-\subsction seq_ev_queue Scheduling queue
+\subsection seq_ev_queue Scheduling queue
 
 An event can be delivered either on scheduled or direct dispatch mode.
 On the scheduling mode, an event is once stored on the priority queue
@@ -978,6 +978,7 @@ int snd_seq_open(snd_seq_t **seqp, const char *name,
  * \brief Open the ALSA sequencer using local configuration
  *
  * \param seqp Pointer to a snd_seq_t pointer.
+ * \param name The name to open
  * \param streams The read/write mode of the sequencer.
  * \param mode Optional modifier
  * \param lconf Local configuration
@@ -997,7 +998,7 @@ int snd_seq_open_lconf(snd_seq_t **seqp, const char *name,
 
 /**
  * \brief Close the sequencer
- * \param handle Handle returned from #snd_seq_open()
+ * \param seq Handle returned from #snd_seq_open()
  * \return 0 on success otherwise a negative error code
  *
  * Closes the sequencer client and releases its resources.
@@ -1275,7 +1276,7 @@ int snd_seq_system_info_malloc(snd_seq_system_info_t **ptr)
 
 /**
  * \brief Frees a previously allocated #snd_seq_system_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_system_info_free(snd_seq_system_info_t *obj)
 {
@@ -1416,7 +1417,7 @@ int snd_seq_client_info_malloc(snd_seq_client_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_client_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_client_info_free(snd_seq_client_info_t *obj)
 {
@@ -1734,7 +1735,7 @@ int snd_seq_port_info_malloc(snd_seq_port_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_port_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_port_info_free(snd_seq_port_info_t *obj)
 {
@@ -2016,7 +2017,7 @@ void snd_seq_port_info_set_capability(snd_seq_port_info_t *info, unsigned int ca
 /**
  * \brief Get the type bits of a port_info container
  * \param info port_info container
- * \return port type bits
+ * \param type port type bits
  *
  * \sa snd_seq_get_port_info(), snd_seq_port_info_get_type()
  */
@@ -2304,7 +2305,7 @@ int snd_seq_port_subscribe_malloc(snd_seq_port_subscribe_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_port_subscribe_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_port_subscribe_free(snd_seq_port_subscribe_t *obj)
 {
@@ -2326,7 +2327,6 @@ void snd_seq_port_subscribe_copy(snd_seq_port_subscribe_t *dst, const snd_seq_po
 /**
  * \brief Get sender address of a port_subscribe container
  * \param info port_subscribe container
- * \param addr sender address
  *
  * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_sender()
  */
@@ -2339,7 +2339,6 @@ const snd_seq_addr_t *snd_seq_port_subscribe_get_sender(const snd_seq_port_subsc
 /**
  * \brief Get destination address of a port_subscribe container
  * \param info port_subscribe container
- * \param addr destination address
  *
  * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_dest()
  */
@@ -2564,7 +2563,7 @@ int snd_seq_query_subscribe_malloc(snd_seq_query_subscribe_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_query_subscribe_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_query_subscribe_free(snd_seq_query_subscribe_t *obj)
 {
@@ -2848,7 +2847,7 @@ int snd_seq_queue_info_malloc(snd_seq_queue_info_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_queue_info_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_queue_info_free(snd_seq_queue_info_t *obj)
 {
@@ -3110,7 +3109,6 @@ int snd_seq_query_named_queue(snd_seq_t *seq, const char *name)
  * \brief Get the queue usage flag to the client
  * \param seq sequencer handle
  * \param q queue id
- * \param client client id
  * \return 1 = client is allowed to access the queue, 0 = not allowed, 
  *     otherwise a negative error code
  *
@@ -3133,7 +3131,6 @@ int snd_seq_get_queue_usage(snd_seq_t *seq, int q)
  * \brief Set the queue usage flag to the client
  * \param seq sequencer handle
  * \param q queue id
- * \param client client id
  * \param used non-zero if the client is allowed
  * \return 0 on success otherwise a negative error code
  *
@@ -3176,7 +3173,7 @@ int snd_seq_queue_status_malloc(snd_seq_queue_status_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_queue_status_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_queue_status_free(snd_seq_queue_status_t *obj)
 {
@@ -3237,7 +3234,6 @@ snd_seq_tick_time_t snd_seq_queue_status_get_tick_time(const snd_seq_queue_statu
 /**
  * \brief Get the real time of a queue_status container
  * \param info queue_status container
- * \param time real time
  *
  * \sa snd_seq_get_queue_status()
  */
@@ -3304,7 +3300,7 @@ int snd_seq_queue_tempo_malloc(snd_seq_queue_tempo_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_queue_tempo_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_queue_tempo_free(snd_seq_queue_tempo_t *obj)
 {
@@ -3504,7 +3500,7 @@ int snd_seq_queue_timer_malloc(snd_seq_queue_timer_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_queue_timer_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_queue_timer_free(snd_seq_queue_timer_t *obj)
 {
@@ -4127,7 +4123,7 @@ int snd_seq_remove_events_malloc(snd_seq_remove_events_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_remove_events_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_remove_events_free(snd_seq_remove_events_t *obj)
 {
@@ -4487,7 +4483,7 @@ int snd_seq_client_pool_malloc(snd_seq_client_pool_t **ptr)
 
 /**
  * \brief frees a previously allocated #snd_seq_client_pool_t
- * \param pointer to object to free
+ * \param obj pointer to object to free
  */
 void snd_seq_client_pool_free(snd_seq_client_pool_t *obj)
 {
@@ -4699,7 +4695,7 @@ int snd_instr_header_malloc(snd_instr_header_t **ptr, size_t len)
 
 /**
  * \brief frees a previously allocated #snd_instr_header_t
- * \param pointer to object to free
+ * \param obj poitner to object to free
  */
 void snd_instr_header_free(snd_instr_header_t *obj)
 {

src/seq/seq_hw.c

@@ -29,6 +29,7 @@
 const char *_snd_module_seq_hw = "";
 #endif
 
+#ifndef DOC_HIDDEN
 #define SNDRV_FILE_SEQ		"/dev/snd/seq"
 #define SNDRV_FILE_ALOADSEQ	"/dev/aloadSEQ"
 #define SNDRV_SEQ_VERSION_MAX	SNDRV_PROTOCOL_VERSION(1, 0, 1)
@@ -36,6 +37,7 @@ const char *_snd_module_seq_hw = "";
 typedef struct {
 	int fd;
 } snd_seq_hw_t;
+#endif /* DOC_HIDDEN */
 
 static int snd_seq_hw_close(snd_seq_t *seq)
 {

src/seq/seq_midi_event.c

@@ -78,6 +78,7 @@ static void songpos_decode(const snd_seq_event_t *ev, unsigned char *buf);
 /*
  * event list
  */
+#ifndef DOC_HIDDEN
 static struct status_event_list_t {
 	int event;
 	int qlen;
@@ -124,9 +125,8 @@ static struct extra_event_list_t {
 	{SND_SEQ_EVENT_REGPARAM, extra_decode_xrpn},
 };
 
-#ifndef DOC_HIDDEN
 #define numberof(ary)	(sizeof(ary)/sizeof(ary[0]))
-#endif
+#endif /* DOC_HIDDEN */
 
 /**
  * \brief Initialize MIDI event parser
@@ -159,7 +159,7 @@ int snd_midi_event_new(size_t bufsize, snd_midi_event_t **rdev)
 
 /**
  * \brief Free MIDI event parser
- * \param rdev MIDI event parser
+ * \param dev MIDI event parser
  * \return 0 on success otherwise a negative error code
  *
  * Frees MIDI event parser.

src/seq/seqmid.c

@@ -107,6 +107,7 @@ int snd_seq_delete_simple_port(snd_seq_t *seq, int port)
 
 /**
  * \brief simple subscription (w/o exclusive & time conversion)
+ * \param seq sequencer handle
  * \param myport the port id as receiver
  * \param src_client sender client id
  * \param src_port sender port id
@@ -133,6 +134,7 @@ int snd_seq_connect_from(snd_seq_t *seq, int myport, int src_client, int src_por
 
 /**
  * \brief simple subscription (w/o exclusive & time conversion)
+ * \param seq sequencer handle
  * \param myport the port id as sender
  * \param dest_client destination client id
  * \param dest_port destination port id
@@ -159,6 +161,7 @@ int snd_seq_connect_to(snd_seq_t *seq, int myport, int dest_client, int dest_por
 
 /**
  * \brief simple disconnection
+ * \param seq sequencer handle
  * \param myport the port id as receiver
  * \param src_client sender client id
  * \param src_port sender port id
@@ -185,6 +188,7 @@ int snd_seq_disconnect_from(snd_seq_t *seq, int myport, int src_client, int src_
 
 /**
  * \brief simple disconnection
+ * \param seq sequencer handle
  * \param myport the port id as sender
  * \param dest_client destination client id
  * \param dest_port destination port id

src/shmarea.c

@@ -27,17 +27,28 @@
 #include <sys/shm.h>
 #include "list.h"
 
+#ifndef DOC_HIDDEN
 struct snd_shm_area {
 	struct list_head list;
 	int shmid;
 	void *ptr;
 	int share;
 };
+#endif
 
 static LIST_HEAD(shm_areas);
 
+/**
+ * \brief Create a shm area record
+ * \param shmid IPC SHM ID
+ * \param ptr the shared area pointer
+ * \return The allocated shm area record, NULL if fail
+ *
+ * Allocates a shared area record with the given SHM ID and pointer.
+ * The record has a reference counter, which is initialized to 1 by this function.
+ */
 struct snd_shm_area *snd_shm_area_create(int shmid, void *ptr)
-{
+p{
 	struct snd_shm_area *area = malloc(sizeof(*area));
 	if (area) {
 		area->shmid = shmid;
@@ -48,6 +59,13 @@ struct snd_shm_area *snd_shm_area_create(int shmid, void *ptr)
 	return area;
 }
 
+/**
+ * \brief Increase the reference counter of shm area record
+ * \param area shm area record
+ * \return the shm area record (identical with the argument)
+ *
+ * Increases the reference counter of the given shared area record.
+ */
 struct snd_shm_area *snd_shm_area_share(struct snd_shm_area *area)
 {
 	if (area == NULL)
@@ -56,6 +74,14 @@ struct snd_shm_area *snd_shm_area_share(struct snd_shm_area *area)
 	return area;
 }
 
+/**
+ * \brief Release the shared area record
+ * \param area the shared are record
+ * \return 0 if successful, or a negative error code
+ *
+ * Decreases the reference counter of the given shared area record, and
+ * releases the resources automaticall if it reaches to 0.
+ */
 int snd_shm_area_destroy(struct snd_shm_area *area)
 {
 	if (area == NULL)

src/timer/timer.c

@@ -436,7 +436,7 @@ size_t snd_timer_info_sizeof()
 
 /**
  * \brief allocate a new snd_timer_info_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_timer_info_t structure using the standard
@@ -555,7 +555,7 @@ size_t snd_timer_params_sizeof()
 
 /**
  * \brief allocate a new snd_timer_params_t structure
- * \param ptr returned pointer
+ * \param params returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_timer_params_t structure using the standard
@@ -597,6 +597,7 @@ void snd_timer_params_copy(snd_timer_params_t *dst, const snd_timer_params_t *sr
 /**
  * \brief set timer auto start
  * \param params pointer to #snd_timer_params_t structure
+ * \param auto_start The boolean value to set
  */
 int snd_timer_params_set_auto_start(snd_timer_params_t * params, int auto_start)
 {
@@ -622,6 +623,7 @@ int snd_timer_params_get_auto_start(snd_timer_params_t * params)
 /**
  * \brief set timer exclusive use
  * \param params pointer to #snd_timer_params_t structure
+ * \param exclusive The boolean value to set
  */
 #ifndef DOXYGEN
 int INTERNAL(snd_timer_params_set_exclusive)(snd_timer_params_t * params, int exclusive)
@@ -657,6 +659,7 @@ use_default_symbol_version(__snd_timer_params_get_exclusive, snd_timer_params_ge
 /**
  * \brief set timer early event
  * \param params pointer to #snd_timer_params_t structure
+ * \param early_event The boolean value to set
  */
 int snd_timer_params_set_early_event(snd_timer_params_t * params, int early_event)
 {
@@ -682,6 +685,7 @@ int snd_timer_params_get_early_event(snd_timer_params_t * params)
 /**
  * \brief set timer ticks
  * \param params pointer to #snd_timer_params_t structure
+ * \param ticks Ticks to set
  */
 void snd_timer_params_set_ticks(snd_timer_params_t * params, long ticks)
 {
@@ -703,6 +707,7 @@ long snd_timer_params_get_ticks(snd_timer_params_t * params)
 /**
  * \brief set timer queue size (32-1024)
  * \param params pointer to #snd_timer_params_t structure
+ * \param queue_size The queue size to set
  */
 void snd_timer_params_set_queue_size(snd_timer_params_t * params, long queue_size)
 {
@@ -724,6 +729,7 @@ long snd_timer_params_get_queue_size(snd_timer_params_t * params)
 /**
  * \brief set timer event filter
  * \param params pointer to #snd_timer_params_t structure
+ * \param filter The event filter bits to set
  */
 #ifndef DOXYGEN
 void INTERNAL(snd_timer_params_set_filter)(snd_timer_params_t * params, unsigned int filter)
@@ -776,7 +782,7 @@ size_t snd_timer_status_sizeof()
 
 /**
  * \brief allocate a new snd_timer_status_t structure
- * \param ptr returned pointer
+ * \param status returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_timer_status_t structure using the standard

src/timer/timer_local.h

@@ -24,6 +24,7 @@
 #include <limits.h>
 #include "local.h"
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	int (*close)(snd_timer_t *timer);
 	int (*nonblock)(snd_timer_t *timer, int nonblock);
@@ -48,8 +49,6 @@ struct _snd_timer {
 	struct list_head async_handlers;
 };
 
-int snd_timer_hw_open(snd_timer_t **handle, const char *name, int dev_class, int dev_sclass, int card, int device, int subdevice, int mode);
-
 typedef struct {
 	int (*close)(snd_timer_query_t *timer);
 	int (*next_device)(snd_timer_query_t *timer, snd_timer_id_t *tid);
@@ -66,6 +65,9 @@ struct _snd_timer_query {
 	snd_timer_query_ops_t *ops;
 	void *private_data;
 };
+#endif /* DOC_HIDDEN */
+
+int snd_timer_hw_open(snd_timer_t **handle, const char *name, int dev_class, int dev_sclass, int card, int device, int subdevice, int mode);
 
 int snd_timer_query_hw_open(snd_timer_query_t **handle, const char *name, int mode);
 

src/timer/timer_query.c

@@ -231,7 +231,7 @@ size_t snd_timer_ginfo_sizeof(void)
 
 /**
  * \brief allocate a new snd_timer_ginfo_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_timer_info_t structure using the standard
@@ -273,6 +273,7 @@ void snd_timer_ginfo_copy(snd_timer_ginfo_t *dst, const snd_timer_ginfo_t *src)
 /**
  * \brief set timer identification
  * \param obj pointer to #snd_timer_ginfo_t structure
+ * \param tid pointer to #snd_timer_id_t structure
  * \return zero on success otherwise a negative error number
  */
 int snd_timer_ginfo_set_tid(snd_timer_ginfo_t *obj, snd_timer_id_t *tid)
@@ -436,7 +437,7 @@ size_t snd_timer_id_sizeof()
 
 /**
  * \brief allocate a new snd_timer_id_t structure
- * \param ptr returned pointer
+ * \param info returned pointer
  * \return 0 on success otherwise a negative error code if fails
  *
  * Allocates a new snd_timer_id_t structure using the standard
@@ -510,7 +511,7 @@ void snd_timer_id_set_sclass(snd_timer_id_t * tid, int dev_sclass)
 
 /**
  * \brief get timer sub-class
- * \param params pointer to #snd_timer_id_t structure
+ * \param tid pointer to #snd_timer_id_t structure
  * \return timer sub-class
  */
 int snd_timer_id_get_sclass(snd_timer_id_t * tid)
@@ -532,7 +533,7 @@ void snd_timer_id_set_card(snd_timer_id_t * tid, int card)
 
 /**
  * \brief get timer card
- * \param params pointer to #snd_timer_id_t structure
+ * \param tid pointer to #snd_timer_id_t structure
  * \return timer card number
  */
 int snd_timer_id_get_card(snd_timer_id_t * tid)
@@ -554,7 +555,7 @@ void snd_timer_id_set_device(snd_timer_id_t * tid, int device)
 
 /**
  * \brief get timer device
- * \param params pointer to #snd_timer_id_t structure
+ * \param tid pointer to #snd_timer_id_t structure
  * \return timer device number
  */
 int snd_timer_id_get_device(snd_timer_id_t * tid)
@@ -576,7 +577,7 @@ void snd_timer_id_set_subdevice(snd_timer_id_t * tid, int subdevice)
 
 /**
  * \brief get timer subdevice
- * \param params pointer to #snd_timer_id_t structure
+ * \param tid pointer to #snd_timer_id_t structure
  * \return timer subdevice number
  */
 int snd_timer_id_get_subdevice(snd_timer_id_t * tid)

src/userfile.c

@@ -23,6 +23,15 @@
 #include <wordexp.h>
 #include <assert.h>
 
+/**
+ * \brief Get the full file name
+ * \param file The file name string to parse
+ * \param result The pointer to store the resultant file name
+ * \return 0 if successful, or a negative error code
+ *
+ * Parses the given file name with POSIX-Shell-like expansion and
+ * stores the first matchine one.  The returned string is strdup'ed.
+ */
 int snd_user_file(const char *file, char **result)
 {
 	wordexp_t we;