ctl: improve documentation for ALSACtl

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

diff --git a/doc/reference/ctl/alsactl-docs.xml b/doc/reference/ctl/alsactl-docs.xml
index 3bd850d0b4d40d9c810706ca4e68b6ae55ed5236..1a71241ddaa399e882698f275bcb3bec5ccf7f34 100644 (file)
--- a/doc/reference/ctl/alsactl-docs.xml
+++ b/doc/reference/ctl/alsactl-docs.xml
@@ -15,10 +15,10 @@
     <chapter id="introduction">
         <title>Introduction</title>
         <para>This library is designed for applications to manipulate ALSA
-        control character device and operate functionality on sound card
-        abstracted as element. Event dispatching is based on GLib's GMainContext
-        and GMainLoop with created GSource.
-        </para>
+        control character device and operate control functionality abstracted
+        as card and element. ALSACtlCard represent the card. It holds file
+        descriptor and creates GSource for event dispatching by GLib's
+        GMainContext/GMainLoop.</para>
     </chapter>
 
     <chapter id="alsactl-enumerations">

diff --git a/src/ctl/card-info.c b/src/ctl/card-info.c
index 159226b554f92eb829e682c8a50aaed6575ea971..b56607baf7e02f9ae51725053d80297af4740b02 100644 (file)
--- a/src/ctl/card-info.c
+++ b/src/ctl/card-info.c
@@ -8,8 +8,10 @@
  *                     sound card
  *
  * A #ALSACtlCardInfo is a GObject-derived object to represent information of
- * sound card. A call of alsactl_card_get_info() returns an instance of the
+ * sound card. The call of alsactl_card_get_info() returns an instance of the
  * object.
+ *
+ * The object wraps 'struct snd_ctl_card_info' in UAPI of Linux sound subsystem.
  */
 struct _ALSACtlCardInfoPrivate {
     struct snd_ctl_card_info info;

diff --git a/src/ctl/card.c b/src/ctl/card.c
index f0f7e0fbdb657b1867d8e1a20d9f2956a170c022..c99a096dafbadde4ceba02e7d20a970caaca6da8 100644 (file)
--- a/src/ctl/card.c
+++ b/src/ctl/card.c
@@ -25,6 +25,8 @@
  * A #ALSACtlCard is a GObject-derived object to represent sound card.
  * Applications use the instance of object to manipulate functionalities on
  * sound card.
+ * After the call of alsactl_card_open() for the numerical ID of sound card,
+ * the object maintains file descriptor till object destruction.
  */
 struct _ALSACtlCardPrivate {
     int fd;

diff --git a/src/ctl/elem-id.c b/src/ctl/elem-id.c
index f2cb8086625a3b1f994002de0b40c9edaa57f0d7..35033e1a040f3b931a70059d1dd4edb9dc021c0e 100644 (file)
--- a/src/ctl/elem-id.c
+++ b/src/ctl/elem-id.c
@@ -6,10 +6,12 @@
  * @Title: ALSACtlElemId
  * @Short_description: A boxed object to represent the identifier of element.
  *
- * A #ALSACtlElemId is an boxed object to represent the identifier of element.
+ * A #ALSACtlElemId is a boxed object to represent the identifier of element.
  * It points to a element by two ways; by the numerical ID, or by the
  * combination of the type of interface, the numerical ID of device, the
  * numerical ID of subdevice, the name, and the index.
+ *
+ * The object wraps 'struct snd_ctl_elem_id' in UAPI of Linux sound subsystem.
  */
 ALSACtlElemId *ctl_elem_id_copy(const ALSACtlElemId *self)
 {

diff --git a/src/ctl/elem-info.c b/src/ctl/elem-info.c
index f7bbe537e10591ad6baae62561a244f37a7bcb67..a21fdd3fc3f12c7647a4c4ba721be51a0fa2fb89 100644 (file)
--- a/src/ctl/elem-info.c
+++ b/src/ctl/elem-info.c
@@ -9,6 +9,8 @@
  *
  * A #ALSACtlElemInfo is an abstract object to represent the common information
  * of any type of element.
+ *
+ * The object wraps 'struct snd_ctl_elem_info' in UAPI of Linux sound subsystem.
  */
 struct _ALSACtlElemInfoPrivate {
     struct snd_ctl_elem_info info;

diff --git a/src/ctl/elem-value.c b/src/ctl/elem-value.c
index 36ab140cd42cde9275a700c8c389da7f09caa79b..95040aee8821aa373769485fec8d1364f6a3f46d 100644 (file)
--- a/src/ctl/elem-value.c
+++ b/src/ctl/elem-value.c
@@ -10,8 +10,10 @@
  * A #ALSACtlElemValue is boxed object to represent the container of values for
  * any type of element. The arrays of values for each type of element shares the
  * same storage, thus it's important for applications to distinguish the type of
- * element in advance of accesing the array. The object is used for the call of
+ * element in advance of accessing the array. The object is used for the call of
  * alsactl_card_write_elem_value() and alsactl_card_read_elem_value().
+ *
+ * The object wraps 'struct snd_ctl_elem_value' in UAPI of Linux sound subsystem.
  */
 struct _ALSACtlElemValuePrivate {
     struct snd_ctl_elem_value value;

diff --git a/src/ctl/query.c b/src/ctl/query.c
index d50c2b4f4bc188caf205fe7518b45650d2b6c7c0..c5eb24ed30fb7441726f68f7a403d8430cbc0e3e 100644 (file)
--- a/src/ctl/query.c
+++ b/src/ctl/query.c
@@ -15,7 +15,8 @@
 /**
  * SECTION: query
  * @Title: Global functions in ALSACtl
- * @Short_description: Global functions in ALSACtl
+ * @Short_description: Global functions available without holding any file
+ *                     descriptor
  */
 
 // For error handling.