timer: fulfill documentation for ALSATimer

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

diff --git a/doc/reference/timer/alsatimer-docs.xml b/doc/reference/timer/alsatimer-docs.xml
index 4bb39815bbb86323b69543cb1de2daaf072c668a..11e605f294e815cbf06de9ee360f6f9b71ff2b53 100644 (file)
--- a/doc/reference/timer/alsatimer-docs.xml
+++ b/doc/reference/timer/alsatimer-docs.xml
@@ -12,6 +12,15 @@
     </releaseinfo>
     </bookinfo>
 
+    <chapter id="introduction">
+        <title>Introduction</title>
+        <para>This library is designed for applications to manipulate ALSA
+        timer character device and operate timer functionality abstracted
+        as timer device and user instance. ALSATimerUserInstance represents
+        the user instance. It holds file descriptor and creates GSource for
+        event dispatching by GLib's GMainContext/GMainLoop.</para>
+    </chapter>
+
     <chapter id="alsatimer-enumerations">
         <title>ALSATimer enumerations</title>
         <xi:include href="xml/alsatimer-enum-types.xml"/>

diff --git a/src/timer/device-id.c b/src/timer/device-id.c
index 2d5bc217bea73b7e0cb368ba06ec91c4022ba4e0..5eaf4837e22238fa8009d826e1e07deff56b6451 100644 (file)
--- a/src/timer/device-id.c
+++ b/src/timer/device-id.c
@@ -1,6 +1,19 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "device-id.h"
 
+/**
+ * SECTION: device-id
+ * @Title: ALSATimerDeviceId
+ * @Short_description: A boxed object to represent the identifier of timer
+ *                     device.
+ *
+ * A #ALSATimerDeviceId is a boxed object to represent the identifier of timer
+ * device. The identifier mainly consists of the class of timer device. The
+ * other members; the numerical ID of card, device, and subdevice are optional
+ * according to the class of timer device.
+ *
+ * The object wraps 'struct snd_timer_id' in UAPI of Linux sound subsystem.
+ */
 ALSATimerDeviceId *timer_device_id_copy(const ALSATimerDeviceId *self)
 {
     return g_memdup(self, sizeof(*self));

diff --git a/src/timer/device-info.c b/src/timer/device-info.c
index bd245f4029eccaa79ee8df895dc0d0545bf05edb..8df40deb1975fe45efa22e35ed7f4b5b35c62361 100644 (file)
--- a/src/timer/device-info.c
+++ b/src/timer/device-info.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: device-info
+ * @Title: ALSATimerDeviceInfo
+ * @Short_description: A GObject-derived object to represent information of
+ *                     timer device.
+ *
+ * A #ALSATimerDeviceInfo is a GObject-derived object to represent information
+ * of timer device. The call of alsatimer_get_device_info() returns an instance
+ * of the object according to the identifier of timer device.
+ *
+ * The object wraps 'struct snd_timer_ginfo' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerDeviceInfoPrivate {
     struct snd_timer_ginfo info;
 };

diff --git a/src/timer/device-params.c b/src/timer/device-params.c
index 71682b4ea032c860feadae102ef47a1b34ffcb24..9702189cf2204ee2062612d0e56e635ec5ca82a0 100644 (file)
--- a/src/timer/device-params.c
+++ b/src/timer/device-params.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: device-params
+ * @Title: ALSATimerDeviceParams
+ * @Short_description: A GObject-derived object to represent parameter of timer
+ *                     device.
+ *
+ * A #ALSATimerDeviceParams is a GObject-derived object to represent parameter
+ * of timer device. The call of alsatimer_set_device_params() requires the
+ * instance of object.
+ *
+ * The object wraps 'struct snd_timer_gparams' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerDeviceParamsPrivate {
     struct snd_timer_gparams params;
 };

diff --git a/src/timer/device-status.c b/src/timer/device-status.c
index 233f9d2f5f6ce5d4dc3c2753815bda3872e9a553..1b4c441ec8eb2000efdf9d6678bc58ddefb2c2b0 100644 (file)
--- a/src/timer/device-status.c
+++ b/src/timer/device-status.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: device-status
+ * @Title: ALSATimerDeviceStatus
+ * @Short_description: A GObject-derived object to represent status of timer
+ *                     device.
+ *
+ * A #ALSATimerDeviceStatus is a GObject-derived object to represent status of
+ * timer device. The call of alsatimer_get_device_status() returns the instance
+ * of object.
+ *
+ * The object wraps 'struct snd_timer_gstatus' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerDeviceStatusPrivate {
     struct snd_timer_gstatus status;
 };

diff --git a/src/timer/event-data-tick.c b/src/timer/event-data-tick.c
index 1337a087fb0d9405a3b582f361c4dd61e4704093..401011936f2f35ddb1333fe3e34b86438cfba33b 100644 (file)
--- a/src/timer/event-data-tick.c
+++ b/src/timer/event-data-tick.c
@@ -2,6 +2,19 @@
 #include "event-data-tick.h"
 #include "privates.h"
 
+/**
+ * SECTION: event-data-tick
+ * @Title: ALSATimerEventDataTick
+ * @Short_description: A GObject-derived object to represent event of timer with
+ *                     tick count
+ *
+ * A #ALSATimerEventDataTick is a GObject-derived object to represent event of
+ * timer with tick count. The instance of object is passed to handler for
+ * 'handle-event' GObject signal in ALSATimerUserInstance when it's available.
+ * The object inherits properties of #ALSATimerEventData.
+ *
+ * The object wraps 'struct snd_timer_read' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerEventDataTickPrivate {
     struct snd_timer_read event;
 };

diff --git a/src/timer/event-data-timestamp.c b/src/timer/event-data-timestamp.c
index 69d6725742a904aba1dadc1b5b20da493f4938de..0f72774a06b50d8714c20ffc2a7006105d33410d 100644 (file)
--- a/src/timer/event-data-timestamp.c
+++ b/src/timer/event-data-timestamp.c
@@ -2,6 +2,21 @@
 #include "event-data-timestamp.h"
 #include "privates.h"
 
+/**
+ * SECTION: event-data-timestamp
+ * @Title: ALSATimerEventDataTimestamp
+ * @Short_description: A GObject-derived object to represent event of timer with
+ *                     timestamp
+ *
+ * A #ALSATimerEventDataTimestamp is a GObject-derived object to represent
+ * event of timer with timestamp. The instance of object is passed to handler for
+ * 'handle-event' GObject signal in ALSATimerUserInstance when it's available.
+ * The source of timestamp is decided by 'timer_tstamp_monotonic' option of
+ * 'snd-timer' kernel module. The object inherits properties of
+ * #ALSATimerEventData.
+ *
+ * The object wraps 'struct snd_timer_read' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerEventDataTimestampPrivate {
     struct snd_timer_tread event;
 };

diff --git a/src/timer/event-data.c b/src/timer/event-data.c
index 296ad3db96ec115d77e4e547afb94cb3f1b47c9d..3d6d9d0f4c95efc3b96054f448960b6b52ee6a07 100644 (file)
--- a/src/timer/event-data.c
+++ b/src/timer/event-data.c
@@ -1,6 +1,15 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "event-data.h"
 
+/**
+ * SECTION: event-data
+ * @Title: ALSATimerEventData
+ * @Short_description: A GObject-derived abstract object to represent common
+ *                     data of event
+ *
+ * A #ALSATimerEventData is a GObject-derived abstract object to represent
+ * common data of event.
+ */
 struct _ALSATimerEventDataPrivate {
     ALSATimerEventDataType type;
 };

diff --git a/src/timer/instance-info.c b/src/timer/instance-info.c
index c1cc9603f0479206c17d6b6eb16b38d77cd62e7f..9679578601068848f629df0c216761c9434acf61 100644 (file)
--- a/src/timer/instance-info.c
+++ b/src/timer/instance-info.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: instance-info
+ * @Title: ALSATimerInstanceInfo
+ * @Short_description: A GObject-derived object to represent information of
+ *                     user instance
+ *
+ * A #ALSATimerInstanceInfo is a GObject-derived object to represent information
+ * of user instance attached to any timer device or the other instance as slave.
+ * The call of alsatimer_user_instance_get_info() returns the instance of object.
+ *
+ * The object wraps 'struct snd_timer_info' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerInstanceInfoPrivate {
     struct snd_timer_info info;
 };

diff --git a/src/timer/instance-params.c b/src/timer/instance-params.c
index 0a15302fadebb3955c374a629e83363737f58d88..a97fb147f5f6d09d26fcb9af6d3ebf03cdd0ae48 100644 (file)
--- a/src/timer/instance-params.c
+++ b/src/timer/instance-params.c
@@ -6,6 +6,19 @@
 
 #include <errno.h>
 
+/**
+ * SECTION: instance-params
+ * @Title: ALSATimerInstanceParams
+ * @Short_description: A GObject-derived object to represent parameters of user
+ *                     instance
+ *
+ * A #ALSATimerInstanceParams is a GObject-derived object to represent
+ * parameters of user instance attached to any timer device or the other
+ * instance as slave. The call of alsatimer_user_instance_set_params() requires
+ * the instance of object.
+ *
+ * The object wraps 'struct snd_timer_params' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerInstanceParamsPrivate{
     struct snd_timer_params params;
 };

diff --git a/src/timer/instance-status.c b/src/timer/instance-status.c
index d06dbd10ad0bddfdd3354d7732c7760ef750dace..0c8a57ada9006bc9b2b86abc3afe7d6116c982af 100644 (file)
--- a/src/timer/instance-status.c
+++ b/src/timer/instance-status.c
@@ -3,6 +3,19 @@
 
 #include <sound/asound.h>
 
+/**
+ * SECTION: instance-status
+ * @Title: ALSATimerInstanceStatus
+ * @Short_description: A GObject-derived object to represent status of user
+ *                     instance
+ *
+ * A #ALSATimerInstanceStatus is a GObject-derived object to represent status
+ * of user instance attached to any timer device or the other instance as slave.
+ * The call of alsatimer_user_instance_get_status() returns the instance of
+ * object.
+ *
+ * The object wraps 'struct snd_timer_status' in UAPI of Linux sound subsystem.
+ */
 struct _ALSATimerInstanceStatusPrivate {
     struct snd_timer_status status;
 };

diff --git a/src/timer/query.c b/src/timer/query.c
index 4a8a8dd37298c4a5b12237cc71a33a21ecaa0fab..baa6becedba9243c5e23f8a2a151702c30405ef2 100644 (file)
--- a/src/timer/query.c
+++ b/src/timer/query.c
@@ -17,6 +17,13 @@
 
 #define TIMER_SYSNAME_TEMPLATE  "timer"
 
+/**
+ * SECTION: query
+ * @Title: Global functions in ALSATimer
+ * @Short_description: Global functions available without holding any
+ *                     file descriptor
+ */
+
 // For error handling.
 G_DEFINE_QUARK("alsatimer-error", alsatimer_error)
 

diff --git a/src/timer/user-instance.c b/src/timer/user-instance.c
index 365956c9849f84631db8cb2619c4c05e7372432b..c436a21086e3e8ddcc64cb4b8fcd8bc6f194ab22 100644 (file)
--- a/src/timer/user-instance.c
+++ b/src/timer/user-instance.c
@@ -10,6 +10,19 @@
 #include <sys/ioctl.h>
 #include <errno.h>
 
+/**
+ * SECTION: user-instance
+ * @Title: ALSATimerUserInstance
+ * @Short_description: A GObject-derived object to represent user instance
+ *
+ * A #ALSATimerUserInstance is a GObject-derived object to represent information
+ * of user instance attached to any timer device or the other instance as slave.
+ * After calling alsatimer_user_instance_open(), the object maintains file
+ * descriptor till object destruction. After calling
+ * alsatimer_user_instance_attach() or alsatimer_user_instance_attach_as_slave(),
+ * the user instance is attached to any timer device or the other instance as
+ * slave.
+ */
 struct _ALSATimerUserInstancePrivate {
     int fd;
     ALSATimerEventDataType event_data_type;