From cc7a8b2fe1459ec7885a40417e4de5224de3894e Mon Sep 17 00:00:00 2001 From: Takashi Sakamoto Date: Thu, 4 Jun 2020 16:20:48 +0900 Subject: [PATCH] ctl: fulfill documentation for ALSACtl Signed-off-by: Takashi Sakamoto --- doc/reference/ctl/alsactl-docs.xml | 11 ++++++++++- src/ctl/card-info.c | 10 ++++++++++ src/ctl/card.c | 24 +++++++++++++++++++++--- src/ctl/elem-id.c | 10 ++++++++++ src/ctl/elem-info-bool.c | 12 ++++++++++++ src/ctl/elem-info-bytes.c | 12 ++++++++++++ src/ctl/elem-info-enum.c | 12 ++++++++++++ src/ctl/elem-info-iec60958.c | 13 +++++++++++++ src/ctl/elem-info-int.c | 12 ++++++++++++ src/ctl/elem-info-int64.c | 12 ++++++++++++ src/ctl/elem-info.c | 9 +++++++++ src/ctl/elem-value.c | 12 ++++++++++++ src/ctl/query.c | 6 ++++++ 13 files changed, 151 insertions(+), 4 deletions(-) diff --git a/doc/reference/ctl/alsactl-docs.xml b/doc/reference/ctl/alsactl-docs.xml index 16d0e67..3bd850d 100644 --- a/doc/reference/ctl/alsactl-docs.xml +++ b/doc/reference/ctl/alsactl-docs.xml @@ -12,6 +12,15 @@ + + Introduction + 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. + + + ALSACtl enumerations @@ -25,7 +34,6 @@ ALSACtl objects - @@ -36,6 +44,7 @@ + diff --git a/src/ctl/card-info.c b/src/ctl/card-info.c index 40a03c5..159226b 100644 --- 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 d4d7d6c..f0f7e0f 100644 --- a/src/ctl/card.c +++ b/src/ctl/card.c @@ -17,6 +17,15 @@ #include #include +/** + * 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 f8ea445..f2cb808 100644 --- 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 be75dfd..e0bd4f6 100644 --- 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 9db4576..b0e60e5 100644 --- 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 13725fd..0b11f52 100644 --- 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 2960101..63bfd81 100644 --- 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 9c6f23c..d3d673a 100644 --- 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 9a489ca..dbbde24 100644 --- 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 79744de..f7bbe53 100644 --- 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 deeec86..36ab140 100644 --- 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 47499a9..d50c2b4 100644 --- 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) -- 2.47.3