More doxygen comments

Added more doxygen comments in pcm_extplug and pcm_ioplug codes.

6 files changed, 457 insertions, 145 deletions

diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
index 8c50578f..5f830b1a 100644
--- a/doc/doxygen.cfg
+++ b/doc/doxygen.cfg
@@ -62,6 +62,8 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_asym.c \
 		   ../src/pcm/pcm_iec958.c \
 		   ../src/pcm/pcm_softvol.c \
+		   ../src/pcm/pcm_extplug.c \
+		   ../src/pcm/pcm_ioplug.c \
 		   ../src/pcm/pcm_misc.c \
 		   ../src/rawmidi \
 		   ../src/timer \
diff --git a/include/pcm_extplug.h b/include/pcm_extplug.h
index 9ea667f9..85c9e29b 100644
--- a/include/pcm_extplug.h
+++ b/include/pcm_extplug.h
@@ -22,48 +22,94 @@
 #ifndef __ALSA_PCM_EXTPLUG_H
 #define __ALSA_PCM_EXTPLUG_H
 
-/* hw constraints */
+/** hw constraints for extplug */
 enum {
-	SND_PCM_EXTPLUG_HW_FORMAT,
-	SND_PCM_EXTPLUG_HW_CHANNELS,
-	SND_PCM_EXTPLUG_HW_PARAMS
+	SND_PCM_EXTPLUG_HW_FORMAT,	/**< format */
+	SND_PCM_EXTPLUG_HW_CHANNELS,	/**< channels */
+	SND_PCM_EXTPLUG_HW_PARAMS	/**< max number of hw constraints */
 };
 	
 typedef struct snd_pcm_extplug snd_pcm_extplug_t;
 typedef struct snd_pcm_extplug_callback snd_pcm_extplug_callback_t;
 
-/* exported pcm data */
+/** handle of extplug */
 struct snd_pcm_extplug {
-	/* must be filled before calling snd_pcm_extplug_create() */
+	/**
+	 * name of this plugin; must be filled before calling #snd_pcm_extplug_create()
+	 */
 	const char *name;
+	/**
+	 * callbacks of this plugin; must be filled before calling #snd_pcm_extplug_create()
+	 */
 	const snd_pcm_extplug_callback_t *callback;
+	/**
+	 * private data, which can be used freely in the driver callbacks
+	 */
 	void *private_data;
-	/* filled by snd_pcm_extplug_open() */
+	/**
+	 * PCM handle filled by #snd_pcm_extplug_create()
+	 */
 	snd_pcm_t *pcm;
-	/* read-only status */
+	/**
+	 * stream direction; read-only status
+	 */
 	snd_pcm_stream_t stream;
-	/* filled in hw_params */
+	/**
+	 * format hw parameter; filled after hw_params is caled
+	 */
 	snd_pcm_format_t format;
+	/**
+	 * subformat hw parameter; filled after hw_params is caled
+	 */
 	snd_pcm_subformat_t subformat;
+	/**
+	 * channels hw parameter; filled after hw_params is caled
+	 */
 	unsigned int channels;
+	/**
+	 * rate hw parameter; filled after hw_params is caled
+	 */
 	unsigned int rate;
+	/**
+	 * slave_format hw parameter; filled after hw_params is caled
+	 */
 	snd_pcm_format_t slave_format;
+	/**
+	 * slave_subformat hw parameter; filled after hw_params is caled
+	 */
 	snd_pcm_subformat_t slave_subformat;
+	/**
+	 * slave_channels hw parameter; filled after hw_params is caled
+	 */
 	unsigned int slave_channels;
 };
 
-/* callback table */
+/** callback table of extplug */
 struct snd_pcm_extplug_callback {
-	/* required */
+	/**
+	 * transfer between source and destination; this is a required callback
+	 */
 	snd_pcm_sframes_t (*transfer)(snd_pcm_extplug_t *ext,
 				      const snd_pcm_channel_area_t *dst_areas,
 				      snd_pcm_uframes_t dst_offset,
 				      const snd_pcm_channel_area_t *src_areas,
 				      snd_pcm_uframes_t src_offset,
 				      snd_pcm_uframes_t size);
+	/**
+	 * close the PCM; optional
+	 */
 	int (*close)(snd_pcm_extplug_t *ext);
+	/**
+	 * hw_params; optional
+	 */
 	int (*hw_params)(snd_pcm_extplug_t *ext, snd_pcm_hw_params_t *params);
+	/**
+	 * hw_free; optional
+	 */
 	int (*hw_free)(snd_pcm_extplug_t *ext);
+	/**
+	 * dump; optional
+	 */
 	void (*dump)(snd_pcm_extplug_t *ext, snd_output_t *out);
 };
 
diff --git a/include/pcm_ioplug.h b/include/pcm_ioplug.h
index 03b0540b..b4781ac0 100644
--- a/include/pcm_ioplug.h
+++ b/include/pcm_ioplug.h
@@ -22,70 +22,123 @@
 #ifndef __ALSA_PCM_IOPLUG_H
 #define __ALSA_PCM_IOPLUG_H
 
-/* hw constraints */
+/** hw constraints for ioplug */
 enum {
-	SND_PCM_IOPLUG_HW_ACCESS = 0,
-	SND_PCM_IOPLUG_HW_FORMAT,
-	SND_PCM_IOPLUG_HW_CHANNELS,
-	SND_PCM_IOPLUG_HW_RATE,
-	SND_PCM_IOPLUG_HW_PERIOD_BYTES,
-	SND_PCM_IOPLUG_HW_BUFFER_BYTES,
-	SND_PCM_IOPLUG_HW_PERIODS,
-	SND_PCM_IOPLUG_HW_PARAMS
+	SND_PCM_IOPLUG_HW_ACCESS = 0,	/**< access type */
+	SND_PCM_IOPLUG_HW_FORMAT,	/**< format */
+	SND_PCM_IOPLUG_HW_CHANNELS,	/**< channels */
+	SND_PCM_IOPLUG_HW_RATE,		/**< rate */
+	SND_PCM_IOPLUG_HW_PERIOD_BYTES,	/**< period bytes */
+	SND_PCM_IOPLUG_HW_BUFFER_BYTES,	/**< buffer bytes */
+	SND_PCM_IOPLUG_HW_PERIODS,	/**< number of periods */
+	SND_PCM_IOPLUG_HW_PARAMS	/**< max number of hw constraints */
 };
 	
 typedef struct snd_pcm_ioplug snd_pcm_ioplug_t;
 typedef struct snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t;
 
-#define SND_PCM_IOPLUG_FLAG_LISTED	(1<<0)
+/**
+ * bit flags for additional conditions
+ */
+#define SND_PCM_IOPLUG_FLAG_LISTED	(1<<0)		/* list up this PCM */
 
-/* exported pcm data */
+/** handle of ioplug */
 struct snd_pcm_ioplug {
-	/* must be filled before calling snd_pcm_ioplug_create() */
+	/**
+	 * name of this plugin; must be filled before calling #snd_pcm_ioplug_create()
+	 */
 	const char *name;
-	unsigned int flags;	/* SND_PCM_IOPLUG_FLAG_XXX */
-	int poll_fd;
-	unsigned int poll_events;
-	unsigned int mmap_rw;		/* pseudo mmap */
+	unsigned int flags;	/**< SND_PCM_IOPLUG_FLAG_XXX */
+	int poll_fd;		/**< poll file descriptor */
+	unsigned int poll_events;	/**< poll events */
+	unsigned int mmap_rw;		/**< pseudo mmap mode */
+	/**
+	 * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create()
+	 */
 	const snd_pcm_ioplug_callback_t *callback;
+	/**
+	 * private data, which can be used freely in the driver callbacks
+	 */
 	void *private_data;
-	/* filled by snd_pcm_ioplug_open() */
+	/**
+	 * PCM handle filled by #snd_pcm_extplug_create()
+	 */
 	snd_pcm_t *pcm;
-	/* read-only status */
-	snd_pcm_stream_t stream;
-	snd_pcm_state_t state;
-	volatile snd_pcm_uframes_t appl_ptr;
-	volatile snd_pcm_uframes_t hw_ptr;
-	int nonblock;
-	/* filled in hw_params */
-	snd_pcm_access_t access;
-	snd_pcm_format_t format;
-	unsigned int channels;
-	unsigned int rate;
-	snd_pcm_uframes_t period_size;
-	snd_pcm_uframes_t buffer_size;
+
+	snd_pcm_stream_t stream;	/* stream direcion; read-only */	
+	snd_pcm_state_t state;		/* current PCM state; read-only */
+	volatile snd_pcm_uframes_t appl_ptr;	/* application pointer; read-only */
+	volatile snd_pcm_uframes_t hw_ptr;	/* hw pointer; read-only */
+	int nonblock;			/* non-block mode; read-only */
+
+	snd_pcm_access_t access;	/* access type; filled after hw_params is called */
+	snd_pcm_format_t format;	/* format; filled after hw_params is called */
+	unsigned int channels;		/* channels; filled after hw_params is called */
+	unsigned int rate;		/* rate; filled after hw_params is called */
+	snd_pcm_uframes_t period_size;	/* period size; filled after hw_params is called */
+	snd_pcm_uframes_t buffer_size;	/* buffer size; filled after hw_params is called */
 };
 
-/* callback table */
+/** callback table of ioplug */
 struct snd_pcm_ioplug_callback {
-	/* required */
+	/**
+	 * start the PCM; required
+	 */
 	int (*start)(snd_pcm_ioplug_t *io);
+	/**
+	 * stop the PCM; required
+	 */
 	int (*stop)(snd_pcm_ioplug_t *io);
+	/**
+	 * get the current DMA position; required
+	 */
 	snd_pcm_sframes_t (*pointer)(snd_pcm_ioplug_t *io);
-	/* optional */
+	/**
+	 * transfer the data; optional
+	 */
 	snd_pcm_sframes_t (*transfer)(snd_pcm_ioplug_t *io,
 				      const snd_pcm_channel_area_t *areas,
 				      snd_pcm_uframes_t offset,
 				      snd_pcm_uframes_t size);
+	/**
+	 * close the PCM; optional
+	 */
 	int (*close)(snd_pcm_ioplug_t *io);
+	/**
+	 * hw_params; optional
+	 */
 	int (*hw_params)(snd_pcm_ioplug_t *io, snd_pcm_hw_params_t *params);
+	/**
+	 * hw_free; optional
+	 */
 	int (*hw_free)(snd_pcm_ioplug_t *io);
+	/**
+	 * sw_params; optional
+	 */
 	int (*sw_params)(snd_pcm_ioplug_t *io, snd_pcm_sw_params_t *params);
+	/**
+	 * prepare; optional
+	 */
 	int (*prepare)(snd_pcm_ioplug_t *io);
+	/**
+	 * drain; optional
+	 */
 	int (*drain)(snd_pcm_ioplug_t *io);
+	/**
+	 * toggle pause; optional
+	 */
 	int (*pause)(snd_pcm_ioplug_t *io, int enable);
+	/**
+	 * resume; optional
+	 */
 	int (*resume)(snd_pcm_ioplug_t *io);
+	/**
+	 * mangle poll events; optional
+	 */
 	int (*poll_revents)(snd_pcm_ioplug_t *io, struct pollfd *pfd, unsigned int nfds, unsigned short *revents);
+	/**
+	 * dump; optional
+	 */
 	void (*dump)(snd_pcm_ioplug_t *io, snd_output_t *out);
 };
 
diff --git a/src/Versions b/src/Versions
index e093deda..1e2b1a4b 100644
--- a/src/Versions
+++ b/src/Versions
@@ -189,4 +189,6 @@ ALSA_1.0.9 {
     snd_pcm_extplug_set_slave_param_list;
     snd_pcm_extplug_set_slave_param_minmax;
 
+    snd_pcm_parse_control_id;
+
 } ALSA_1.0.5;
diff --git a/src/pcm/pcm_extplug.c b/src/pcm/pcm_extplug.c
index 24137e6e..42628c45 100644
--- a/src/pcm/pcm_extplug.c
+++ b/src/pcm/pcm_extplug.c
@@ -1,7 +1,7 @@
 /**
  * \file pcm/pcm_extplug.c
  * \ingroup Plugin_SDK
- * \brief External Plugin SDK
+ * \brief External Filter Plugin SDK
  * \author Takashi Iwai <tiwai@suse.de>
  * \date 2005
  */
@@ -31,6 +31,8 @@
 #include "pcm_extplug.h"
 #include "pcm_ext_parm.h"
 
+#ifndef DOC_HIDDEN
+
 typedef struct snd_pcm_extplug_priv {
 	snd_pcm_plugin_t plug;
 	snd_pcm_extplug_t *data;
@@ -54,8 +56,8 @@ static unsigned int excl_parbits[SND_PCM_EXTPLUG_HW_PARAMS] = {
 };
 
 /*
+ * set min/max values for the given parameter
  */
-
 int snd_ext_parm_set_minmax(struct snd_ext_parm *parm, unsigned int min, unsigned int max)
 {
 	parm->num_list = 0;
@@ -67,6 +69,9 @@ int snd_ext_parm_set_minmax(struct snd_ext_parm *parm, unsigned int min, unsigne
 	return 0;
 }
 
+/*
+ * set the list of available values for the given parameter
+ */
 static int val_compar(const void *ap, const void *bp)
 {
 	return *(const unsigned int *)ap - *(const unsigned int *)bp;
@@ -95,6 +100,9 @@ void snd_ext_parm_clear(struct snd_ext_parm *parm)
 	memset(parm, 0, sizeof(*parm));
 }
 
+/*
+ * limit the interval to the given list
+ */
 int snd_interval_list(snd_interval_t *ival, int num_list, unsigned int *list)
 {
 	int imin, imax;
@@ -129,6 +137,9 @@ int snd_interval_list(snd_interval_t *ival, int num_list, unsigned int *list)
 	return changed;
 }
 
+/*
+ * refine the interval parameter
+ */
 int snd_ext_parm_interval_refine(snd_interval_t *ival, struct snd_ext_parm *parm, int type)
 {
 	parm += type;
@@ -147,6 +158,9 @@ int snd_ext_parm_interval_refine(snd_interval_t *ival, struct snd_ext_parm *parm
 	return 0;
 }
 
+/*
+ * refine the mask parameter
+ */
 int snd_ext_parm_mask_refine(snd_mask_t *mask, struct snd_ext_parm *parm, int type)
 {
 	snd_mask_t bits;
@@ -161,8 +175,8 @@ int snd_ext_parm_mask_refine(snd_mask_t *mask, struct snd_ext_parm *parm, int ty
 
 
 /*
+ * hw_refine callback
  */
-
 static int extplug_hw_refine(snd_pcm_hw_params_t *hw_params,
 			     struct snd_ext_parm *parm)
 {
@@ -268,6 +282,9 @@ static int snd_pcm_extplug_hw_refine(snd_pcm_t *pcm, snd_pcm_hw_params_t *params
 				       snd_pcm_generic_hw_refine);
 }
 
+/*
+ * hw_params callback
+ */
 static int snd_pcm_extplug_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
 
@@ -294,6 +311,9 @@ static int snd_pcm_extplug_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params
 	return 0;
 }
 
+/*
+ * hw_free callback
+ */
 static int snd_pcm_extplug_hw_free(snd_pcm_t *pcm)
 {
 	extplug_priv_t *ext = pcm->private_data;
@@ -304,6 +324,9 @@ static int snd_pcm_extplug_hw_free(snd_pcm_t *pcm)
 	return 0;
 }
 
+/*
+ * write_areas skeleton - call transfer callback
+ */
 static snd_pcm_uframes_t
 snd_pcm_extplug_write_areas(snd_pcm_t *pcm,
 			    const snd_pcm_channel_area_t *areas,
@@ -317,12 +340,15 @@ snd_pcm_extplug_write_areas(snd_pcm_t *pcm,
 
 	if (size > *slave_sizep)
 		size = *slave_sizep;
-	ext->data->callback->transfer(ext->data, slave_areas, slave_offset,
-				      areas, offset, size);
+	size = ext->data->callback->transfer(ext->data, slave_areas, slave_offset,
+					     areas, offset, size);
 	*slave_sizep = size;
 	return size;
 }
 
+/*
+ * read_areas skeleton - call transfer callback
+ */
 static snd_pcm_uframes_t
 snd_pcm_extplug_read_areas(snd_pcm_t *pcm,
 			   const snd_pcm_channel_area_t *areas,
@@ -336,12 +362,15 @@ snd_pcm_extplug_read_areas(snd_pcm_t *pcm,
 
 	if (size > *slave_sizep)
 		size = *slave_sizep;
-	ext->data->callback->transfer(ext->data, areas, offset,
-				      slave_areas, slave_offset, size);
+	size = ext->data->callback->transfer(ext->data, areas, offset,
+					     slave_areas, slave_offset, size);
 	*slave_sizep = size;
 	return size;
 }
 
+/*
+ * dump setup
+ */
 static void snd_pcm_extplug_dump(snd_pcm_t *pcm, snd_output_t *out)
 {
 	extplug_priv_t *ext = pcm->private_data;
@@ -399,63 +428,41 @@ static snd_pcm_ops_t snd_pcm_extplug_ops = {
 	.munmap = snd_pcm_generic_munmap,
 };
 
+#endif /* !DOC_HIDDEN */
+
 /*
+ * Exported functions
  */
-void snd_pcm_extplug_params_reset(snd_pcm_extplug_t *extplug)
-{
-	extplug_priv_t *ext = extplug->pcm->private_data;
-	clear_ext_params(ext);
-}
 
-int snd_pcm_extplug_set_slave_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
-{
-	extplug_priv_t *ext = extplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	return snd_ext_parm_set_list(&ext->sparams[type], num_list, list);
-}
+/*! \page pcm_external_plugins
 
-int snd_pcm_extplug_set_slave_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
-{
-	extplug_priv_t *ext = extplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	if (is_mask_type(type)) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	return snd_ext_parm_set_minmax(&ext->sparams[type], min, max);
-}
+\section pcm_extplug External Plugin: Filter-Type Plugin
 
-int snd_pcm_extplug_set_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
-{
-	extplug_priv_t *ext = extplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	return snd_ext_parm_set_list(&ext->params[type], num_list, list);
-}
+The filter-type plugin is a plugin to convert the PCM signals from the input
+and feeds to the output.  Thus, this plugin always needs a slave PCM as its output.
 
-int snd_pcm_extplug_set_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
-{
-	extplug_priv_t *ext = extplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	if (is_mask_type(type)) {
-		SNDERR("EXTPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	return snd_ext_parm_set_minmax(&ext->params[type], min, max);
-}
+The plugin can modify the format and the channels of the input/output PCM.
+It can <i>not</i> modify the sample rate (because of simplicity reason).
 
-/*
+*/
+
+/**
+ * \brief Create an extplug instance
+ * \param extplug the extplug handle
+ * \param name name of the PCM
+ * \param root configuration tree root
+ * \param slave_conf slave configuration root
+ * \param stream stream direction
+ * \param mode PCM open mode
+ * \return 0 if successful, or a negative error code
+ *
+ * Creates the extplug instance based on the given handle.
+ * The slave_conf argument is mandatory, and usually taken from the config tree of the
+ * PCM plugin as "slave" config value.
+ * name, root, stream and mode arguments are the values used for opening the PCM.
+ *
+ * The callback is the mandatory field of extplug handle.  At least, transfer callback
+ * must be set before calling this function.
  */
 int snd_pcm_extplug_create(snd_pcm_extplug_t *extplug, const char *name,
 			   snd_config_t *root, snd_config_t *slave_conf,
@@ -466,8 +473,10 @@ int snd_pcm_extplug_create(snd_pcm_extplug_t *extplug, const char *name,
 	snd_pcm_t *spcm, *pcm;
 	snd_config_t *sconf;
 
+	assert(root);
 	assert(extplug && extplug->callback);
 	assert(extplug->callback->transfer);
+	assert(slave_conf);
 
 	err = snd_pcm_slave_conf(root, slave_conf, &sconf, 0);
 	if (err < 0)
@@ -510,7 +519,125 @@ int snd_pcm_extplug_create(snd_pcm_extplug_t *extplug, const char *name,
 	return 0;
 }
 
+/**
+ * \brief Delete the extplug instance
+ * \param extplug the extplug handle to delete
+ * \return 0 if successful, or a negative error code
+ *
+ * The destructor of extplug instance.
+ * Closes the PCM and deletes the associated resources.
+ */
 int snd_pcm_extplug_delete(snd_pcm_extplug_t *extplug)
 {
 	return snd_pcm_close(extplug->pcm);
 }
+
+
+/**
+ * \brief Reset extplug parameters
+ * \param extplug the extplug handle
+ *
+ * Resets the all parameters for the given extplug handle.
+ */
+void snd_pcm_extplug_params_reset(snd_pcm_extplug_t *extplug)
+{
+	extplug_priv_t *ext = extplug->pcm->private_data;
+	clear_ext_params(ext);
+}
+
+/**
+ * \brief Set slave parameter as the list
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the slave parameter as the list.
+ * The available values of the given parameter type of the slave PCM is restricted
+ * to the ones of the given list.
+ */
+int snd_pcm_extplug_set_slave_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
+{
+	extplug_priv_t *ext = extplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	return snd_ext_parm_set_list(&ext->sparams[type], num_list, list);
+}
+
+/**
+ * \brief Set slave parameter as the min/max values
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the slave parameter as the min/max values.
+ * The available values of the given parameter type of the slave PCM is restricted
+ * between the given minimum and maximum values.
+ */
+int snd_pcm_extplug_set_slave_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
+{
+	extplug_priv_t *ext = extplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	if (is_mask_type(type)) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	return snd_ext_parm_set_minmax(&ext->sparams[type], min, max);
+}
+
+/**
+ * \brief Set master parameter as the list
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the master parameter as the list.
+ * The available values of the given parameter type of this PCM (as input) is restricted
+ * to the ones of the given list.
+ */
+int snd_pcm_extplug_set_param_list(snd_pcm_extplug_t *extplug, int type, unsigned int num_list, const unsigned int *list)
+{
+	extplug_priv_t *ext = extplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	return snd_ext_parm_set_list(&ext->params[type], num_list, list);
+}
+
+/**
+ * \brief Set master parameter as the min/max values
+ * \param extplug the extplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the master parameter as the min/max values.
+ * The available values of the given parameter type of this PCM (as input) is restricted
+ * between the given minimum and maximum values.
+ */
+int snd_pcm_extplug_set_param_minmax(snd_pcm_extplug_t *extplug, int type, unsigned int min, unsigned int max)
+{
+	extplug_priv_t *ext = extplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_EXTPLUG_HW_PARAMS) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	if (is_mask_type(type)) {
+		SNDERR("EXTPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	return snd_ext_parm_set_minmax(&ext->params[type], min, max);
+}
+
diff --git a/src/pcm/pcm_ioplug.c b/src/pcm/pcm_ioplug.c
index bf8c9882..5bb90e26 100644
--- a/src/pcm/pcm_ioplug.c
+++ b/src/pcm/pcm_ioplug.c
@@ -30,6 +30,8 @@
 #include "pcm_ioplug.h"
 #include "pcm_ext_parm.h"
 
+#ifndef DOC_HIDDEN
+
 /* hw_params */
 typedef struct snd_pcm_ioplug_priv {
 	snd_pcm_ioplug_t *data;
@@ -700,55 +702,35 @@ static snd_pcm_fast_ops_t snd_pcm_ioplug_fast_ops = {
 	.mmap_commit = snd_pcm_ioplug_mmap_commit,
 };
 
-void snd_pcm_ioplug_params_reset(snd_pcm_ioplug_t *ioplug)
-{
-	ioplug_priv_t *io = ioplug->pcm->private_data;
-	clear_io_params(io);
-}
+#endif /* !DOC_HIDDEN */
 
-int snd_pcm_ioplug_set_param_list(snd_pcm_ioplug_t *ioplug, int type, unsigned int num_list, const unsigned int *list)
-{
-	ioplug_priv_t *io = ioplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
-		SNDERR("IOPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	if (type == SND_PCM_IOPLUG_HW_PERIODS)
-		io->params[type].integer = 1;
-	return snd_ext_parm_set_list(&io->params[type], num_list, list);
-}
+/*
+ * Exported functions
+ */
 
-int snd_pcm_ioplug_set_param_minmax(snd_pcm_ioplug_t *ioplug, int type, unsigned int min, unsigned int max)
-{
-	ioplug_priv_t *io = ioplug->pcm->private_data;
-	if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
-		SNDERR("IOPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	if (type == SND_PCM_IOPLUG_HW_ACCESS || type == SND_PCM_IOPLUG_HW_FORMAT) {
-		SNDERR("IOPLUG: invalid parameter type %d", type);
-		return -EINVAL;
-	}
-	if (type == SND_PCM_IOPLUG_HW_PERIODS)
-		io->params[type].integer = 1;
-	return snd_ext_parm_set_minmax(&io->params[type], min, max);
-}
+/*! \page pcm_external_plugins
 
-int snd_pcm_ioplug_reinit_status(snd_pcm_ioplug_t *ioplug)
-{
-	ioplug->pcm->poll_fd = ioplug->poll_fd;
-	ioplug->pcm->poll_events = ioplug->poll_events;
-	ioplug->pcm->mmap_rw = ioplug->mmap_rw;
-	return 0;
-}
+\section pcm_ioplug External Plugin: I/O Plugin
 
-const snd_pcm_channel_area_t *snd_pcm_ioplug_mmap_areas(snd_pcm_ioplug_t *ioplug)
-{
-	if (ioplug->mmap_rw)
-		return snd_pcm_mmap_areas(ioplug->pcm);
-	return NULL;
-}
+The I/O-type plugin is a PCM plugin to work as the input or output terminal point,
+i.e. as a user-space PCM driver.
 
+*/
+
+/**
+ * \brief Create an ioplug instance
+ * \param ioplug the ioplug handle
+ * \param name name of PCM
+ * \param stream stream direction
+ * \param mode PCM open mode
+ * \return 0 if successful, or a negative error code
+ *
+ * Creates the ioplug instance.
+ *
+ * The callback is the mandatory field of ioplug handle.  At least, start, stop and
+ * pointer callbacks must be set before calling this function.
+ *
+ */
 int snd_pcm_ioplug_create(snd_pcm_ioplug_t *ioplug, const char *name,
 			  snd_pcm_stream_t stream, int mode)
 {
@@ -788,8 +770,108 @@ int snd_pcm_ioplug_create(snd_pcm_ioplug_t *ioplug, const char *name,
 	return 0;
 }
 
+/**
+ * \brief Delete the ioplug instance
+ * \param ioplug the ioplug handle
+ * \return 0 if successful, or a negative error code
+ */
 int snd_pcm_ioplug_delete(snd_pcm_ioplug_t *ioplug)
 {
 	return snd_pcm_close(ioplug->pcm);
 }
 
+
+/**
+ * \brief Reset ioplug parameters
+ * \param ioplug the ioplug handle
+ *
+ * Resets the all parameters for the given ioplug handle.
+ */
+void snd_pcm_ioplug_params_reset(snd_pcm_ioplug_t *ioplug)
+{
+	ioplug_priv_t *io = ioplug->pcm->private_data;
+	clear_io_params(io);
+}
+
+/**
+ * \brief Set parameter as the list
+ * \param ioplug the ioplug handle
+ * \param type parameter type
+ * \param num_list number of available values
+ * \param list the list of available values
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the parameter as the list.
+ * The available values of the given parameter type is restricted to the ones of the given list.
+ */
+int snd_pcm_ioplug_set_param_list(snd_pcm_ioplug_t *ioplug, int type, unsigned int num_list, const unsigned int *list)
+{
+	ioplug_priv_t *io = ioplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
+		SNDERR("IOPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	if (type == SND_PCM_IOPLUG_HW_PERIODS)
+		io->params[type].integer = 1;
+	return snd_ext_parm_set_list(&io->params[type], num_list, list);
+}
+
+/**
+ * \brief Set parameter as the min/max values
+ * \param ioplug the ioplug handle
+ * \param type parameter type
+ * \param min the minimum value
+ * \param max the maximum value
+ * \return 0 if successful, or a negative error code
+ *
+ * Sets the parameter as the min/max values.
+ * The available values of the given parameter type is restricted between the given
+ * minimum and maximum values.
+ */
+int snd_pcm_ioplug_set_param_minmax(snd_pcm_ioplug_t *ioplug, int type, unsigned int min, unsigned int max)
+{
+	ioplug_priv_t *io = ioplug->pcm->private_data;
+	if (type < 0 && type >= SND_PCM_IOPLUG_HW_PARAMS) {
+		SNDERR("IOPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	if (type == SND_PCM_IOPLUG_HW_ACCESS || type == SND_PCM_IOPLUG_HW_FORMAT) {
+		SNDERR("IOPLUG: invalid parameter type %d", type);
+		return -EINVAL;
+	}
+	if (type == SND_PCM_IOPLUG_HW_PERIODS)
+		io->params[type].integer = 1;
+	return snd_ext_parm_set_minmax(&io->params[type], min, max);
+}
+
+/**
+ * \brief Reinitialize the poll and mmap status
+ * \param ioplug the ioplug handle
+ * \return 0 if successful, or a negative error code
+ *
+ * Reinitializes the poll and the mmap status of the PCM.
+ * Call this function to propagate the status change in the ioplug instance to
+ * its PCM internals.
+ */
+int snd_pcm_ioplug_reinit_status(snd_pcm_ioplug_t *ioplug)
+{
+	ioplug->pcm->poll_fd = ioplug->poll_fd;
+	ioplug->pcm->poll_events = ioplug->poll_events;
+	ioplug->pcm->mmap_rw = ioplug->mmap_rw;
+	return 0;
+}
+
+/**
+ * \brief Get mmap area of ioplug
+ * \param ioplug the ioplug handle
+ * \return the mmap channel areas if available, or NULL
+ *
+ * Returns the mmap channel areas if available.  When mmap_rw field is not set,
+ * this function always returns NULL.
+ */
+const snd_pcm_channel_area_t *snd_pcm_ioplug_mmap_areas(snd_pcm_ioplug_t *ioplug)
+{
+	if (ioplug->mmap_rw)
+		return snd_pcm_mmap_areas(ioplug->pcm);
+	return NULL;
+}