Added description of copy, linear, lfloat and mulaw PCM plugins

7 files changed, 354 insertions, 5 deletions

diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
index 8a520908..05da937b 100644
--- a/doc/doxygen.cfg
+++ b/doc/doxygen.cfg
@@ -38,6 +38,10 @@ INPUT            = index.doxygen \
 		   ../src/pcm/pcm_mmap.c \
                    ../src/pcm/pcm_plugin.c \
 		   ../src/pcm/pcm_hw.c \
+		   ../src/pcm/pcm_copy.c \
+		   ../src/pcm/pcm_linear.c \
+		   ../src/pcm/pcm_lfloat.c \
+		   ../src/pcm/pcm_mulaw.c \
 		   ../src/pcm/pcm_hooks.c \
 		   ../src/pcm/pcm_meter.c \
 		   ../src/pcm/pcm_misc.c \
diff --git a/include/pcm_plugin.h b/include/pcm_plugin.h
index db4f1630..c5f8193a 100644
--- a/include/pcm_plugin.h
+++ b/include/pcm_plugin.h
@@ -67,23 +67,68 @@ int _snd_pcm_hw_open(snd_pcm_t **pcmp, const char *name,
 		     snd_config_t *root ATTRIBUTE_UNUSED, snd_config_t *conf,
 		     snd_pcm_stream_t stream, int mode);
 
+/*
+ *  Copy plugin
+ */
 int snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name,
 		      snd_pcm_t *slave, int close_slave);
+int _snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name,
+		       snd_config_t *root, snd_config_t *conf,
+                       snd_pcm_stream_t stream, int mode);
+                                              
+/*
+ *  Linear conversion plugin
+ */
 int snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name,
 			snd_pcm_format_t sformat, snd_pcm_t *slave,
 			int close_slave);
+int _snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name,
+			 snd_config_t *root, snd_config_t *conf,
+			 snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Linear<->Float conversion plugin
+ */
 int snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name,
 			snd_pcm_format_t sformat, snd_pcm_t *slave,
 			int close_slave);
+int _snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name,
+			 snd_config_t *root, snd_config_t *conf,
+			 snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Linear<->mu-Law conversion plugin
+ */
 int snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name,
 		       snd_pcm_format_t sformat, snd_pcm_t *slave,
 		       int close_slave);
+int _snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name,
+			snd_config_t *root, snd_config_t *conf,
+                        snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Linear<->a-Law conversion plugin
+ */
 int snd_pcm_alaw_open(snd_pcm_t **pcmp, const char *name,
 		      snd_pcm_format_t sformat, snd_pcm_t *slave,
 		      int close_slave);
+int _snd_pcm_alaw_open(snd_pcm_t **pcmp, const char *name,
+		       snd_config_t *root, snd_config_t *conf,
+		       snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Linear<->Ima-ADPCM conversion plugin
+ */
 int snd_pcm_adpcm_open(snd_pcm_t **pcmp, const char *name,
 		       snd_pcm_format_t sformat, snd_pcm_t *slave,
 		       int close_slave);
+int _snd_pcm_adpcm_open(snd_pcm_t **pcmp, const char *name,
+			snd_config_t *root, snd_config_t *conf,
+			snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Route plugin for linear formats
+ */
 int snd_pcm_route_load_ttable(snd_config_t *tt, snd_pcm_route_ttable_entry_t *ttable,
 			      unsigned int tt_csize, unsigned int tt_ssize,
 			      unsigned int *tt_cused, unsigned int *tt_sused,
@@ -94,9 +139,19 @@ int snd_pcm_route_open(snd_pcm_t **pcmp, const char *name,
 		       unsigned int tt_ssize,
 		       unsigned int tt_cused, unsigned int tt_sused,
 		       snd_pcm_t *slave, int close_slave);
+int _snd_pcm_route_open(snd_pcm_t **pcmp, const char *name,
+			snd_config_t *root, snd_config_t *conf,
+			snd_pcm_stream_t stream, int mode);
+
+/*
+ *  Rate plugin for linear formats
+ */
 int snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name,
 		      snd_pcm_format_t sformat, unsigned int srate,
 		      snd_pcm_t *slave, int close_slave);
+int _snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name,
+		       snd_config_t *root, snd_config_t *conf,
+		       snd_pcm_stream_t stream, int mode);
 
 /*
  *  Hooks plugin
@@ -107,6 +162,18 @@ int _snd_pcm_hooks_open(snd_pcm_t **pcmp, const char *name,
 			snd_config_t *root, snd_config_t *conf,
 			snd_pcm_stream_t stream, int mode);
 
+/*
+ *  LADSPA plugin
+ */
+int snd_pcm_ladspa_open(snd_pcm_t **pcmp, const char *name,
+			const char *ladspa_path,
+			snd_config_t *ladspa_pplugins,
+			snd_config_t *ladspa_cplugins,
+			snd_pcm_t *slave, int close_slave);
+int _snd_pcm_ladspa_open(snd_pcm_t **pcmp, const char *name,
+			 snd_config_t *root, snd_config_t *conf,
+			 snd_pcm_stream_t stream, int mode);
+
 /** \} */
 
 #endif /* __ALSA_PCM_PLUGIN_H */
diff --git a/src/pcm/pcm_copy.c b/src/pcm/pcm_copy.c
index ae9724af..a0c68fff 100644
--- a/src/pcm/pcm_copy.c
+++ b/src/pcm/pcm_copy.c
@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_copy.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Copy Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
  *  PCM - Copy conversion
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
@@ -28,10 +35,12 @@
 const char *_snd_module_pcm_copy = "";
 #endif
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	/* This field need to be the first */
 	snd_pcm_plugin_t plug;
 } snd_pcm_copy_t;
+#endif
 
 static int snd_pcm_copy_hw_refine_cprepare(snd_pcm_t *pcm ATTRIBUTE_UNUSED, snd_pcm_hw_params_t *params)
 {
@@ -143,7 +152,7 @@ static void snd_pcm_copy_dump(snd_pcm_t *pcm, snd_output_t *out)
 	snd_pcm_dump(copy->plug.slave, out);
 }
 
-snd_pcm_ops_t snd_pcm_copy_ops = {
+static snd_pcm_ops_t snd_pcm_copy_ops = {
 	close: snd_pcm_plugin_close,
 	info: snd_pcm_plugin_info,
 	hw_refine: snd_pcm_copy_hw_refine,
@@ -158,6 +167,17 @@ snd_pcm_ops_t snd_pcm_copy_ops = {
 	munmap: snd_pcm_plugin_munmap,
 };
 
+/**
+ * \brief Creates a new copy PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \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
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name, snd_pcm_t *slave, int close_slave)
 {
 	snd_pcm_t *pcm;
@@ -189,6 +209,48 @@ int snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name, snd_pcm_t *slave, int
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_copy Plugin: copy
+
+This plugin copies samples from master copy PCM to given slave PCM.
+The channel count, format and rate must match for both of them. 
+
+\code
+pcm.name {
+	type copy		# Copy PCM
+	slave STR		# Slave name
+	# or
+	slave {			# Slave definition
+		pcm STR		# Slave PCM name
+		# or
+		pcm { }		# Slave PCM definition
+	}
+}
+\endcode
+
+\subsection pcm_plugins_copy_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_copy_open()
+  <LI>_snd_pcm_copy_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new copy PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with copy PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \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
+ *          changed in future.
+ */
 int _snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name,
 		       snd_config_t *root, snd_config_t *conf, 
 		       snd_pcm_stream_t stream, int mode)
@@ -227,4 +289,6 @@ int _snd_pcm_copy_open(snd_pcm_t **pcmp, const char *name,
 		snd_pcm_close(spcm);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_copy_open, SND_PCM_DLSYM_VERSION);
+#endif
diff --git a/src/pcm/pcm_hw.c b/src/pcm/pcm_hw.c
index 13c32457..17396e66 100644
--- a/src/pcm/pcm_hw.c
+++ b/src/pcm/pcm_hw.c
@@ -1,7 +1,7 @@
 /**
  * \file pcm/pcm_hw.c
  * \ingroup PCM_Plugins
- * \brief PCM HW Interface
+ * \brief PCM HW Plugin Interface
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 2000-2001
diff --git a/src/pcm/pcm_lfloat.c b/src/pcm/pcm_lfloat.c
index 791d0ae6..5b886a56 100644
--- a/src/pcm/pcm_lfloat.c
+++ b/src/pcm/pcm_lfloat.c
@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_lfloat.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Linear<->Float Conversion Plugin Interface
+ * \author Jaroslav Kysela <perex@suse.cz>
+ * \date 2001
+ */
 /*
  *  PCM - Linear Integer <-> Linear Float conversion
  *  Copyright (c) 2001 by Jaroslav Kysela <perex@suse.cz>
@@ -23,6 +30,8 @@
 #include "pcm_local.h"
 #include "pcm_plugin.h"
 
+#ifndef DOC_HIDDEN
+
 typedef float float_t;
 typedef double double_t;
 
@@ -76,8 +85,12 @@ int snd_pcm_lfloat_put_s32_index(snd_pcm_format_t format)
 	return snd_pcm_lfloat_get_s32_index(format);
 }
 
+#endif /* DOC_HIDDEN */
+
 #ifndef BUGGY_GCC
 
+#ifndef DOC_HIDDEN
+
 void snd_pcm_lfloat_convert_integer_float(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,
 					  unsigned int channels, snd_pcm_uframes_t frames,
@@ -169,6 +182,8 @@ void snd_pcm_lfloat_convert_float_integer(const snd_pcm_channel_area_t *dst_area
 	}
 }
 
+#endif /* DOC_HIDDEN */
+
 static int snd_pcm_lfloat_hw_refine_cprepare(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
 	snd_pcm_lfloat_t *lfloat = pcm->private_data;
@@ -334,7 +349,7 @@ static void snd_pcm_lfloat_dump(snd_pcm_t *pcm, snd_output_t *out)
 	snd_pcm_dump(lfloat->plug.slave, out);
 }
 
-snd_pcm_ops_t snd_pcm_lfloat_ops = {
+static snd_pcm_ops_t snd_pcm_lfloat_ops = {
 	close: snd_pcm_plugin_close,
 	info: snd_pcm_plugin_info,
 	hw_refine: snd_pcm_lfloat_hw_refine,
@@ -349,6 +364,18 @@ snd_pcm_ops_t snd_pcm_lfloat_ops = {
 	munmap: snd_pcm_plugin_munmap,
 };
 
+/**
+ * \brief Creates a new linear conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param sformat Slave (destination) format
+ * \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
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sformat, snd_pcm_t *slave, int close_slave)
 {
 	snd_pcm_t *pcm;
@@ -384,6 +411,49 @@ int snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sfo
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_lfloat Plugin: linear<->float
+
+This plugin converts linear to float samples and float to linear samples from master
+linear<->float conversion PCM to given slave PCM. The channel count, format and rate must
+match for both of them.
+
+\code
+pcm.name {
+        type lfloat             # Linear<->Float conversion PCM
+        slave STR               # Slave name
+        # or
+        slave {                 # Slave definition
+                pcm STR         # Slave PCM name
+                # or
+                pcm { }         # Slave PCM definition
+        }
+}
+\endcode
+
+\subsection pcm_plugins_lfloat_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_lfloat_open()
+  <LI>_snd_pcm_lfloat_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new linear<->float conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with copy PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \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
+ *          changed in future.
+ */
 int _snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name,
 			 snd_config_t *root, snd_config_t *conf, 
 			 snd_pcm_stream_t stream, int mode)
@@ -430,7 +500,9 @@ int _snd_pcm_lfloat_open(snd_pcm_t **pcmp, const char *name,
 		snd_pcm_close(spcm);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_lfloat_open, SND_PCM_DLSYM_VERSION);
+#endif
 
 #else /* BUGGY_GCC */
 
diff --git a/src/pcm/pcm_linear.c b/src/pcm/pcm_linear.c
index 8c09af7e..3ce30c2f 100644
--- a/src/pcm/pcm_linear.c
+++ b/src/pcm/pcm_linear.c
@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_linear.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Linear Conversion Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
  *  PCM - Linear conversion
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
@@ -28,12 +35,16 @@
 const char *_snd_module_pcm_linear = "";
 #endif
 
+#ifndef DOC_HIDDEN
 typedef struct {
 	/* This field need to be the first */
 	snd_pcm_plugin_t plug;
 	unsigned int conv_idx;
 	snd_pcm_format_t sformat;
 } snd_pcm_linear_t;
+#endif
+
+#ifndef DOC_HIDDEN
 
 int snd_pcm_linear_convert_index(snd_pcm_format_t src_format,
 				 snd_pcm_format_t dst_format)
@@ -127,6 +138,8 @@ void snd_pcm_linear_convert(const snd_pcm_channel_area_t *dst_areas, snd_pcm_ufr
 	}
 }
 
+#endif /* DOC_HIDDEN */
+
 static int snd_pcm_linear_hw_refine_cprepare(snd_pcm_t *pcm ATTRIBUTE_UNUSED, snd_pcm_hw_params_t *params)
 {
 	int err;
@@ -275,7 +288,7 @@ static void snd_pcm_linear_dump(snd_pcm_t *pcm, snd_output_t *out)
 	snd_pcm_dump(linear->plug.slave, out);
 }
 
-snd_pcm_ops_t snd_pcm_linear_ops = {
+static snd_pcm_ops_t snd_pcm_linear_ops = {
 	close: snd_pcm_plugin_close,
 	info: snd_pcm_plugin_info,
 	hw_refine: snd_pcm_linear_hw_refine,
@@ -290,6 +303,19 @@ snd_pcm_ops_t snd_pcm_linear_ops = {
 	munmap: snd_pcm_plugin_munmap,
 };
 
+
+/**
+ * \brief Creates a new linear conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param sformat Slave (destination) format
+ * \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
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sformat, snd_pcm_t *slave, int close_slave)
 {
 	snd_pcm_t *pcm;
@@ -324,6 +350,48 @@ int snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sfo
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_linear Plugin: linear
+
+This plugin converts linear samples from master linear conversion PCM to given
+slave PCM. The channel count, format and rate must match for both of them.
+
+\code
+pcm.name {
+        type linear             # Linear conversion PCM
+        slave STR               # Slave name
+        # or
+        slave {                 # Slave definition
+                pcm STR         # Slave PCM name
+                # or
+                pcm { }         # Slave PCM definition
+        }
+}
+\endcode
+
+\subsection pcm_plugins_linear_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_linear_open()
+  <LI>_snd_pcm_linear_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new linear conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with copy PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \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
+ *          changed in future.
+ */
 int _snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name,
 			 snd_config_t *root, snd_config_t *conf, 
 			 snd_pcm_stream_t stream, int mode)
@@ -369,4 +437,6 @@ int _snd_pcm_linear_open(snd_pcm_t **pcmp, const char *name,
 		snd_pcm_close(spcm);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_linear_open, SND_PCM_DLSYM_VERSION);
+#endif
diff --git a/src/pcm/pcm_mulaw.c b/src/pcm/pcm_mulaw.c
index 7f31ddc7..1039af2e 100644
--- a/src/pcm/pcm_mulaw.c
+++ b/src/pcm/pcm_mulaw.c
@@ -1,3 +1,10 @@
+/**
+ * \file pcm/pcm_mulaw.c
+ * \ingroup PCM_Plugins
+ * \brief PCM Mu-Law Conversion Plugin Interface
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \date 2000-2001
+ */
 /*
  *  PCM - Mu-Law conversion
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
@@ -28,6 +35,8 @@
 const char *_snd_module_pcm_mulaw = "";
 #endif
 
+#ifndef DOC_HIDDEN
+
 typedef void (*mulaw_f)(const snd_pcm_channel_area_t *src_areas,
 			snd_pcm_uframes_t src_offset,
 			const snd_pcm_channel_area_t *dst_areas,
@@ -43,6 +52,8 @@ typedef struct {
 	snd_pcm_format_t sformat;
 } snd_pcm_mulaw_t;
 
+#endif
+
 static inline int val_seg(int val)
 {
 	int r = 0;
@@ -143,6 +154,8 @@ static int ulaw_to_s16(unsigned char u_val)
 	return ((u_val & 0x80) ? (0x84 - t) : (t - 0x84));
 }
 
+#ifndef DOC_HIDDEN
+
 void snd_pcm_mulaw_decode(const snd_pcm_channel_area_t *dst_areas,
 			  snd_pcm_uframes_t dst_offset,
 			  const snd_pcm_channel_area_t *src_areas,
@@ -218,6 +231,8 @@ void snd_pcm_mulaw_encode(const snd_pcm_channel_area_t *dst_areas,
 	}
 }
 
+#endif /* DOC_HIDDEN */
+
 static int snd_pcm_mulaw_hw_refine_cprepare(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {
 	snd_pcm_mulaw_t *mulaw = pcm->private_data;
@@ -384,7 +399,7 @@ static void snd_pcm_mulaw_dump(snd_pcm_t *pcm, snd_output_t *out)
 	snd_pcm_dump(mulaw->plug.slave, out);
 }
 
-snd_pcm_ops_t snd_pcm_mulaw_ops = {
+static snd_pcm_ops_t snd_pcm_mulaw_ops = {
 	close: snd_pcm_plugin_close,
 	info: snd_pcm_plugin_info,
 	hw_refine: snd_pcm_mulaw_hw_refine,
@@ -399,6 +414,18 @@ snd_pcm_ops_t snd_pcm_mulaw_ops = {
 	munmap: snd_pcm_plugin_munmap,
 };
 
+/**
+ * \brief Creates a new Mu-Law conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param sformat Slave (destination) format
+ * \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
+ * \warning Using of this function might be dangerous in the sense
+ *          of compatibility reasons. The prototype might be freely
+ *          changed in future.
+ */
 int snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sformat, snd_pcm_t *slave, int close_slave)
 {
 	snd_pcm_t *pcm;
@@ -434,6 +461,49 @@ int snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sfor
 	return 0;
 }
 
+/*! \page pcm_plugins
+
+\section pcm_plugins_mulaw Plugin: Mu-Law
+
+This plugin converts Mu-Law samples to linear or linear to Mu-Law samples
+from master Mu-Law conversion PCM to given slave PCM. The channel count,
+format and rate must match for both of them.
+
+\code
+pcm.name {
+        type mulaw              # Mu-Law conversion PCM
+        slave STR               # Slave name
+        # or
+        slave {                 # Slave definition
+                pcm STR         # Slave PCM name
+                # or
+                pcm { }         # Slave PCM definition
+        }
+}
+\endcode
+
+\subsection pcm_plugins_mulaw_funcref Function reference
+
+<UL>
+  <LI>snd_pcm_mulaw_open()
+  <LI>_snd_pcm_mulaw_open()
+</UL>
+
+*/
+
+/**
+ * \brief Creates a new Mu-Law conversion PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration node with copy PCM description
+ * \param stream Stream type
+ * \param mode Stream mode
+ * \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
+ *          changed in future.
+ */
 int _snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name,
 			snd_config_t *root, snd_config_t *conf, 
 			snd_pcm_stream_t stream, int mode)
@@ -480,4 +550,6 @@ int _snd_pcm_mulaw_open(snd_pcm_t **pcmp, const char *name,
 		snd_pcm_close(spcm);
 	return err;
 }
+#ifndef DOC_HIDDEN
 SND_DLSYM_BUILD_VERSION(_snd_pcm_mulaw_open, SND_PCM_DLSYM_VERSION);
+#endif