ctl: fulfill 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 16d0e67f3a09d43a450af850395c8ddd335bc823..3bd850d0b4d40d9c810706ca4e68b6ae55ed5236 100644 (file)
--- a/doc/reference/ctl/alsactl-docs.xml
+++ b/doc/reference/ctl/alsactl-docs.xml
@@ -12,6 +12,15 @@
     </releaseinfo>
     </bookinfo>
 
+    <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>
+    </chapter>
+
     <chapter id="alsactl-enumerations">
         <title>ALSACtl enumerations</title>
         <xi:include href="xml/alsactl-enum-types.xml"/>
@@ -25,7 +34,6 @@
     <chapter id="alsactl-objects">
         <title>ALSACtl objects</title>
         <xi:include href="xml/card.xml"/>
-       <xi:include href="xml/alsactl-sigs-marshal.xml"/>
         <xi:include href="xml/card-info.xml"/>
         <xi:include href="xml/elem-id.xml"/>
         <xi:include href="xml/elem-info.xml"/>
@@ -36,6 +44,7 @@
         <xi:include href="xml/elem-info-iec60958.xml"/>
         <xi:include href="xml/elem-info-int64.xml"/>
         <xi:include href="xml/elem-value.xml"/>
+        <xi:include href="xml/alsactl-sigs-marshal.xml"/>
     </chapter>
 
     <index id="index-all">

diff --git a/src/ctl/card-info.c b/src/ctl/card-info.c
index 40a03c58ce23a6e2de9d1f20ba5b5b5320add0cb..159226b554f92eb829e682c8a50aaed6575ea971 100644 (file)
--- a/src/ctl/card-info.c
+++ b/src/ctl/card-info.c
@@ -1,6 +1,16 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: card-info
+ * @Title: ALSACtlCardInfo
+ * @Short_description: A GObject-derived object to represent information of
+ *                     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
+ * object.
+ */
 struct _ALSACtlCardInfoPrivate {
     struct snd_ctl_card_info info;
 };

diff --git a/src/ctl/card.c b/src/ctl/card.c
index d4d7d6c4d8ee8367fd684e165f5a90829087ebaa..f0f7e0fbdb657b1867d8e1a20d9f2956a170c022 100644 (file)
--- a/src/ctl/card.c
+++ b/src/ctl/card.c
@@ -17,6 +17,15 @@
 #include <sys/ioctl.h>
 #include <unistd.h>
 
+/**
+ * SECTION: card
+ * @Title: ALSACtlCard
+ * @Short_description: An GObject-derived object to represent sound card
+ *
+ * A #ALSACtlCard is a GObject-derived object to represent sound card.
+ * Applications use the instance of object to manipulate functionalities on
+ * sound card.
+ */
 struct _ALSACtlCardPrivate {
     int fd;
     char *devnode;
@@ -417,6 +426,9 @@ void alsactl_card_get_elem_info(ALSACtlCard *self, const ALSACtlElemId *elem_id,
  *             Type-Length-Value data.
  * @container_count: The number of quadlets in the container.
  * @error: A #GError.
+ *
+ * Write the given array of bytes as Type/Length/Value data for element pointed
+ * by the identifier.
  */
 void alsactl_card_write_elem_tlv(ALSACtlCard *self,
                             const ALSACtlElemId *elem_id,
@@ -462,6 +474,9 @@ void alsactl_card_write_elem_tlv(ALSACtlCard *self,
  *             for Type-Length-Value data.
  * @container_count: The number of quadlets in the container.
  * @error: A #GError.
+ *
+ * Read Type/Length/Value data from element pointed by the identifier and fulfil
+ * the given array of bytes with the data.
  */
 void alsactl_card_read_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id,
                             gint32 *const *container, gsize *container_count,
@@ -508,6 +523,9 @@ void alsactl_card_read_elem_tlv(ALSACtlCard *self, const ALSACtlElemId *elem_id,
  *             for Type-Length-Value data.
  * @container_count: The number of quadlets in the container.
  * @error: A #GError.
+ *
+ * Command the given array of bytes as Type/Length/Value data for  element
+ * pointed by the identifier.
  */
 void alsactl_card_command_elem_tlv(ALSACtlCard *self,
                             const ALSACtlElemId *elem_id,
@@ -639,7 +657,7 @@ static void add_or_replace_elems(int fd, const ALSACtlElemId *elem_id,
  * @entries: (element-type ALSACtl.ElemId)(out): The list of added element IDs.
  * @error: A #GError.
  *
- * Add user-defined elements.
+ * Add the user-defined elements and return the list of their identifier.
  */
 void alsactl_card_add_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id,
                             guint elem_count, ALSACtlElemInfo *elem_info,
@@ -665,7 +683,7 @@ void alsactl_card_add_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id,
  * @entries: (element-type ALSACtl.ElemId)(out): The list of renewed element IDs.
  * @error: A #GError.
  *
- * Add user-defined elements instead of given elements.
+ * Add user-defined elements to replace the existent ones.
  */
 void alsactl_card_replace_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id,
                             guint elem_count, ALSACtlElemInfo *elem_info,
@@ -688,7 +706,7 @@ void alsactl_card_replace_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id,
  * @elem_id: A #ALSACtlElemId.
  * @error: A #GError.
  *
- * Remove user-defined elements.
+ * Remove user-defined elements pointed by the identifier.
  */
 void alsactl_card_remove_elems(ALSACtlCard *self, const ALSACtlElemId *elem_id,
                                GError **error)

diff --git a/src/ctl/elem-id.c b/src/ctl/elem-id.c
index f8ea445a2b549db4e36db102cdadc651f3a885ee..f2cb8086625a3b1f994002de0b40c9edaa57f0d7 100644 (file)
--- a/src/ctl/elem-id.c
+++ b/src/ctl/elem-id.c
@@ -1,6 +1,16 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: elem-id
+ * @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.
+ * 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.
+ */
 ALSACtlElemId *ctl_elem_id_copy(const ALSACtlElemId *self)
 {
     return g_memdup(self, sizeof(*self));

diff --git a/src/ctl/elem-info-bool.c b/src/ctl/elem-info-bool.c
index be75dfdbf924739ee8592720d278cb20017e2477..e0bd4f65cc6497bc01066a203f548edee889762c 100644 (file)
--- a/src/ctl/elem-info-bool.c
+++ b/src/ctl/elem-info-bool.c
@@ -2,6 +2,18 @@
 #include "elem-info-bool.h"
 #include "privates.h"
 
+/**
+ * SECTION: elem-info-bool
+ * @Title: ALSACtlElemInfoBool
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of boolean type of element
+ *
+ * A #ALSACtlElemInfoBool is a GObject-derived object to represent the
+ * information of boolean type of element, which contains boolean values. The
+ * object inherits methods and properties of #ALSACtlElemInfo. The call of
+ * alsactl_card_get_elem_info() can returns the instance of object, or the call
+ * of alsactl_card_add_elems() requires the instance of object as argument.
+ */
 G_DEFINE_TYPE(ALSACtlElemInfoBool, alsactl_elem_info_bool, ALSACTL_TYPE_ELEM_INFO)
 
 enum ctl_elem_info_bool_prop_type {

diff --git a/src/ctl/elem-info-bytes.c b/src/ctl/elem-info-bytes.c
index 9db4576f2e76c1002d5e81454b2a2a566e8d5f77..b0e60e5937f75af316aa80674293023aa2a2e98d 100644 (file)
--- a/src/ctl/elem-info-bytes.c
+++ b/src/ctl/elem-info-bytes.c
@@ -2,6 +2,18 @@
 #include "elem-info-bytes.h"
 #include "privates.h"
 
+/**
+ * SECTION: elem-info-bytes
+ * @Title: ALSACtlElemInfoBytes
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of bytes type of element
+ *
+ * A #ALSACtlElemInfoBytes is a GObject-derived object to represent the
+ * information of bytes type of element, which contains byte values. The object
+ * inherits methods and properties of #ALSACtlElemInfo. The call of
+ * alsactl_card_get_elem_info() can returns the instance of object, or the call
+ * of alsactl_card_add_elems() requires the instance of object as argument.
+ */
 G_DEFINE_TYPE(ALSACtlElemInfoBytes, alsactl_elem_info_bytes, ALSACTL_TYPE_ELEM_INFO)
 
 enum ctl_elem_info_bytes_prop_type {

diff --git a/src/ctl/elem-info-enum.c b/src/ctl/elem-info-enum.c
index 13725fde3f7e8aabde1d5991f9b2bd83853090ad..0b11f52abf907033e99305bcbbac2db6a4efe4c7 100644 (file)
--- a/src/ctl/elem-info-enum.c
+++ b/src/ctl/elem-info-enum.c
@@ -2,6 +2,18 @@
 #include "elem-info-enum.h"
 #include "privates.h"
 
+/**
+ * SECTION: elem-info-enum
+ * @Title: ALSACtlElemInfoEnum
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of enumeration type of element
+ *
+ * A #ALSACtlElemInfoEnum is a GObject-derived object to represent the
+ * information of enumeration type of element. The object inherits methods and
+ * properties of #ALSACtlElemInfo. The call of alsactl_card_get_elem_info() can
+ * returns the instance of object, or The call of alsactl_card_add_elems()
+ * requires the instance of object as argument.
+ */
 struct _ALSACtlElemInfoEnumPrivate {
     const gchar **labels;     // should have sentinel member with NULL value.
 };

diff --git a/src/ctl/elem-info-iec60958.c b/src/ctl/elem-info-iec60958.c
index 296010160ee19b6c6d60662f09af1dcd37d87d4e..63bfd8134230bed83b6b4ce77824200cc29c9f16 100644 (file)
--- a/src/ctl/elem-info-iec60958.c
+++ b/src/ctl/elem-info-iec60958.c
@@ -1,6 +1,19 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "elem-info-iec60958.h"
 
+/**
+ * SECTION: elem-info-iec60958
+ * @Title: ALSACtlElemInfoIec60958
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of IEC 60958 type of element
+ *
+ * A #ALSACtlElemInfoIec60958 is a GObject-derived object to represent the
+ * information of IEC 60958 type of element, which contains channel status and
+ * user data. The object inherits methods and properties of #ALSACtlElemInfo.
+ * A call of alsactl_card_get_elem_info() can returns the instance of object,
+ * or a call of alsactl_card_add_elems() requires the instance of object as
+ * argument.
+ */
 G_DEFINE_TYPE(ALSACtlElemInfoIec60958, alsactl_elem_info_iec60958, ALSACTL_TYPE_ELEM_INFO)
 
 static void alsactl_elem_info_iec60958_class_init(ALSACtlElemInfoIec60958Class *klass)

diff --git a/src/ctl/elem-info-int.c b/src/ctl/elem-info-int.c
index 9c6f23cb607c2eed9670565f36ade30181008c42..d3d673ac5635b18a1e877d3e2a10a93fcf46ba9b 100644 (file)
--- a/src/ctl/elem-info-int.c
+++ b/src/ctl/elem-info-int.c
@@ -2,6 +2,18 @@
 #include "elem-info-int.h"
 #include "privates.h"
 
+/**
+ * SECTION: elem-info-int
+ * @Title: ALSACtlElemInfoInt
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of integer type of element
+ *
+ * A #ALSACtlElemInfoInt is a GObject-derived object to represent the
+ * information of integer type of element, which contains integer values. The
+ * object inherits methods and properties of #ALSACtlElemInfo. A call of
+ * alsactl_card_get_elem_info() can returns the instance of object, or a call
+ * of alsactl_card_add_elems() requires the instance of object as argument.
+ */
 G_DEFINE_TYPE(ALSACtlElemInfoInt, alsactl_elem_info_int, ALSACTL_TYPE_ELEM_INFO)
 
 enum ctl_elem_info_int_prop_type {

diff --git a/src/ctl/elem-info-int64.c b/src/ctl/elem-info-int64.c
index 9a489ca1f16fd75dbc8b6c3ad8d907cbd817c0f4..dbbde24ea705d16e91dfe6ba07fc7484d7469d3e 100644 (file)
--- a/src/ctl/elem-info-int64.c
+++ b/src/ctl/elem-info-int64.c
@@ -2,6 +2,18 @@
 #include "elem-info-int64.h"
 #include "privates.h"
 
+/**
+ * SECTION: elem-info-int64
+ * @Title: ALSACtlElemInfoInt64
+ * @Short_description: A GObject-derived object to represent the information
+ *                     of integer64 type of element
+ *
+ * A #ALSACtlElemInfoInt64 is a GObject-derived object to represent the
+ * information of integer type of element, which contains 64 bit integer values.
+ * The object inherits methods and properties of #ALSACtlElemInfo. A call of
+ * alsactl_card_get_elem_info() can returns the instance of object, or a call
+ * of alsactl_card_add_elems() requires the instance of object as argument.
+ */
 G_DEFINE_TYPE(ALSACtlElemInfoInt64, alsactl_elem_info_int64, ALSACTL_TYPE_ELEM_INFO)
 
 enum ctl_elem_info_int64_prop_type {

diff --git a/src/ctl/elem-info.c b/src/ctl/elem-info.c
index 79744de3401836139c38d18685f33e978d528987..f7bbe537e10591ad6baae62561a244f37a7bcb67 100644 (file)
--- a/src/ctl/elem-info.c
+++ b/src/ctl/elem-info.c
@@ -1,6 +1,15 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: elem-info
+ * @Title: ALSACtlElemInfoInt
+ * @Short_description: An abstract object to represent the common information
+ *                     of any type of element
+ *
+ * A #ALSACtlElemInfo is an abstract object to represent the common information
+ * of any type of element.
+ */
 struct _ALSACtlElemInfoPrivate {
     struct snd_ctl_elem_info info;
 };

diff --git a/src/ctl/elem-value.c b/src/ctl/elem-value.c
index deeec8658813528766f79eef65537b3b10d35baa..36ab140cd42cde9275a700c8c389da7f09caa79b 100644 (file)
--- a/src/ctl/elem-value.c
+++ b/src/ctl/elem-value.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: elem-value
+ * @Title: ALSACtlElemValue
+ * @Short_description: A boxed object to represent the container of array of
+ *                     values for any type of element.
+ *
+ * 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
+ * alsactl_card_write_elem_value() and alsactl_card_read_elem_value().
+ */
 struct _ALSACtlElemValuePrivate {
     struct snd_ctl_elem_value value;
 };

diff --git a/src/ctl/query.c b/src/ctl/query.c
index 47499a938549e8f4d10bc88e1b1ea5656b9630e4..d50c2b4f4bc188caf205fe7518b45650d2b6c7c0 100644 (file)
--- a/src/ctl/query.c
+++ b/src/ctl/query.c
@@ -12,6 +12,12 @@
 #define CARD_SYSNAME_TEMPLATE       "card%u"
 #define CONTROL_SYSNAME_TEMPLATE    "controlC%u"
 
+/**
+ * SECTION: query
+ * @Title: Global functions in ALSACtl
+ * @Short_description: Global functions in ALSACtl
+ */
+
 // For error handling.
 G_DEFINE_QUARK("alsactl-error", alsactl_error)