origanized and added some documentation

2 files changed, 62 insertions, 26 deletions

diff --git a/include/tinyalsa/mixer.h b/include/tinyalsa/mixer.h
index ae7c118..4de6133 100644
--- a/include/tinyalsa/mixer.h
+++ b/include/tinyalsa/mixer.h
@@ -28,7 +28,7 @@
 
 /** @file */
 
-/** @defgroup tinyalsa-mixer Mixer Interface
+/** @defgroup libtinyalsa-mixer Mixer Interface
  * @brief All macros, structures and functions that make up the mixer interface.
  */
 
@@ -42,44 +42,58 @@ extern "C" {
 #endif
 
 struct mixer;
+
 struct mixer_ctl;
 
-/* Mixer control types */
+/** Mixer control type.
+ * @ingroup libtinyalsa-mixer
+ */
 enum mixer_ctl_type {
+    /** boolean control type */
     MIXER_CTL_TYPE_BOOL,
+    /** integer control type */
     MIXER_CTL_TYPE_INT,
+    /** an enumerated control type */
     MIXER_CTL_TYPE_ENUM,
     MIXER_CTL_TYPE_BYTE,
     MIXER_CTL_TYPE_IEC958,
+    /** a 64 bit integer control type */
     MIXER_CTL_TYPE_INT64,
+    /** unknown control type */
     MIXER_CTL_TYPE_UNKNOWN,
+    /** end of the enumeration (not a control type) */
     MIXER_CTL_TYPE_MAX,
 };
 
-/* Open and close a mixer */
 struct mixer *mixer_open(unsigned int card);
+
 void mixer_close(struct mixer *mixer);
 
-/* Get info about a mixer */
 const char *mixer_get_name(struct mixer *mixer);
 
-/* Obtain mixer controls */
 unsigned int mixer_get_num_ctls(struct mixer *mixer);
+
 struct mixer_ctl *mixer_get_ctl(struct mixer *mixer, unsigned int id);
+
 struct mixer_ctl *mixer_get_ctl_by_name(struct mixer *mixer, const char *name);
+
 struct mixer_ctl *mixer_get_ctl_by_name_and_index(struct mixer *mixer,
                                                   const char *name,
                                                   unsigned int index);
 
-/* Get info about mixer controls */
 unsigned int mixer_ctl_get_id(struct mixer_ctl *ctl);
+
 const char *mixer_ctl_get_name(struct mixer_ctl *ctl);
+
 enum mixer_ctl_type mixer_ctl_get_type(struct mixer_ctl *ctl);
+
 const char *mixer_ctl_get_type_string(struct mixer_ctl *ctl);
+
 unsigned int mixer_ctl_get_num_values(struct mixer_ctl *ctl);
+
 unsigned int mixer_ctl_get_num_enums(struct mixer_ctl *ctl);
-const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl,
-                                      unsigned int enum_id);
+
+const char *mixer_ctl_get_enum_string(struct mixer_ctl *ctl, unsigned int enum_id);
 
 /* Some sound cards update their controls due to external events,
  * such as HDMI EDID byte data changing when an HDMI cable is
@@ -89,16 +103,22 @@ void mixer_ctl_update(struct mixer_ctl *ctl);
 
 /* Set and get mixer controls */
 int mixer_ctl_get_percent(struct mixer_ctl *ctl, unsigned int id);
+
 int mixer_ctl_set_percent(struct mixer_ctl *ctl, unsigned int id, int percent);
 
 int mixer_ctl_get_value(struct mixer_ctl *ctl, unsigned int id);
+
 int mixer_ctl_get_array(struct mixer_ctl *ctl, void *array, size_t count);
+
 int mixer_ctl_set_value(struct mixer_ctl *ctl, unsigned int id, int value);
+
 int mixer_ctl_set_array(struct mixer_ctl *ctl, const void *array, size_t count);
+
 int mixer_ctl_set_enum_by_string(struct mixer_ctl *ctl, const char *string);
 
 /* Determe range of integer mixer controls */
 int mixer_ctl_get_range_min(struct mixer_ctl *ctl);
+
 int mixer_ctl_get_range_max(struct mixer_ctl *ctl);
 
 #if defined(__cplusplus)
diff --git a/include/tinyalsa/pcm.h b/include/tinyalsa/pcm.h
index 0b02e9d..9d02995 100644
--- a/include/tinyalsa/pcm.h
+++ b/include/tinyalsa/pcm.h
@@ -42,8 +42,6 @@
 extern "C" {
 #endif
 
-struct pcm;
-
 /** A flag that specifies that the PCM is an output.
  * May not be bitwise AND'd with @ref PCM_IN.
  * Used in @ref pcm_open.
@@ -177,8 +175,11 @@ struct pcm_config {
      * stop_threshold    : period_count * period_size
      * silence_threshold : 0
      */
+    /** The minimum number of frames required to start the PCM */
     unsigned int start_threshold;
+    /** The minimum number of frames required to stop the PCM */
     unsigned int stop_threshold;
+    /** The minimum number of frames to silence the PCM */
     unsigned int silence_threshold;
 };
 
@@ -196,7 +197,7 @@ enum pcm_param
     PCM_PARAM_SUBFORMAT,
     /** An interval representing the range of sample bits available (e.g. 8 to 32) */
     PCM_PARAM_SAMPLE_BITS,
-		/** An interval representing the range of frame bits available (e.g. 8 to 64) */
+    /** An interval representing the range of frame bits available (e.g. 8 to 64) */
     PCM_PARAM_FRAME_BITS,
     /** An interval representing the range of channels available (e.g. 1 to 2) */
     PCM_PARAM_CHANNELS,
@@ -205,6 +206,7 @@ enum pcm_param
     PCM_PARAM_PERIOD_TIME,
     /** The number of frames in a period */
     PCM_PARAM_PERIOD_SIZE,
+    /** The number of bytes in a period */
     PCM_PARAM_PERIOD_BYTES,
     /** The number of periods for a PCM */
     PCM_PARAM_PERIODS,
@@ -212,23 +214,31 @@ enum pcm_param
     PCM_PARAM_BUFFER_SIZE,
     PCM_PARAM_BUFFER_BYTES,
     PCM_PARAM_TICK_TIME,
-};
+}; /* enum pcm_param */
 
-struct pcm *pcm_open(unsigned int card, unsigned int device,
-                     unsigned int flags, struct pcm_config *config);
-int pcm_close(struct pcm *pcm);
-int pcm_is_ready(struct pcm *pcm);
+struct pcm_params;
 
 struct pcm_params *pcm_params_get(unsigned int card, unsigned int device,
                                   unsigned int flags);
+
 void pcm_params_free(struct pcm_params *pcm_params);
 
-struct pcm_mask *pcm_params_get_mask(struct pcm_params *pcm_params,
-        enum pcm_param param);
-unsigned int pcm_params_get_min(struct pcm_params *pcm_params,
-                                enum pcm_param param);
-unsigned int pcm_params_get_max(struct pcm_params *pcm_params,
-                                enum pcm_param param);
+struct pcm_mask *pcm_params_get_mask(struct pcm_params *pcm_params, enum pcm_param param);
+
+unsigned int pcm_params_get_min(struct pcm_params *pcm_params, enum pcm_param param);
+
+unsigned int pcm_params_get_max(struct pcm_params *pcm_params, enum pcm_param param);
+
+struct pcm;
+
+struct pcm *pcm_open(unsigned int card,
+                     unsigned int device,
+                     unsigned int flags,
+                     struct pcm_config *config);
+
+int pcm_close(struct pcm *pcm);
+	
+int pcm_is_ready(struct pcm *pcm);
 
 int pcm_get_file_descriptor(struct pcm *pcm);
 
@@ -237,25 +247,31 @@ const char *pcm_get_error(struct pcm *pcm);
 unsigned int pcm_format_to_bits(enum pcm_format format);
 
 unsigned int pcm_get_buffer_size(struct pcm *pcm);
+
 unsigned int pcm_frames_to_bytes(struct pcm *pcm, unsigned int frames);
+
 unsigned int pcm_bytes_to_frames(struct pcm *pcm, unsigned int bytes);
 
-int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail,
-                       struct timespec *tstamp);
+int pcm_get_htimestamp(struct pcm *pcm, unsigned int *avail, struct timespec *tstamp);
 
 unsigned int pcm_get_subdevice(struct pcm *pcm);
 
 int pcm_write(struct pcm *pcm, const void *data, unsigned int count);
+
 int pcm_read(struct pcm *pcm, void *data, unsigned int count);
 
 int pcm_mmap_write(struct pcm *pcm, const void *data, unsigned int count);
+
 int pcm_mmap_read(struct pcm *pcm, void *data, unsigned int count);
-int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset,
-                   unsigned int *frames);
+
+int pcm_mmap_begin(struct pcm *pcm, void **areas, unsigned int *offset, unsigned int *frames);
+
 int pcm_mmap_commit(struct pcm *pcm, unsigned int offset, unsigned int frames);
 
 int pcm_prepare(struct pcm *pcm);
+
 int pcm_start(struct pcm *pcm);
+
 int pcm_stop(struct pcm *pcm);
 
 int pcm_wait(struct pcm *pcm, int timeout);