From: Takashi Sakamoto Date: Fri, 5 Jun 2020 15:30:21 +0000 (+0900) Subject: timer: fulfill documentation for ALSATimer X-Git-Tag: v0.1.0~140 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=ca6a1c5658a8aa1cd2e6f7efd93922f816d844ce;p=alsa-gobject.git timer: fulfill documentation for ALSATimer Signed-off-by: Takashi Sakamoto --- diff --git a/doc/reference/timer/alsatimer-docs.xml b/doc/reference/timer/alsatimer-docs.xml index 4bb3981..11e605f 100644 --- a/doc/reference/timer/alsatimer-docs.xml +++ b/doc/reference/timer/alsatimer-docs.xml @@ -12,6 +12,15 @@ + + Introduction + 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. + + ALSATimer enumerations diff --git a/src/timer/device-id.c b/src/timer/device-id.c index 2d5bc21..5eaf483 100644 --- 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 bd245f4..8df40de 100644 --- 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 71682b4..9702189 100644 --- 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 233f9d2..1b4c441 100644 --- 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 1337a08..4010119 100644 --- 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 69d6725..0f72774 100644 --- 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 296ad3d..3d6d9d0 100644 --- 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 c1cc960..9679578 100644 --- 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 0a15302..a97fb14 100644 --- a/src/timer/instance-params.c +++ b/src/timer/instance-params.c @@ -6,6 +6,19 @@ #include +/** + * 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 d06dbd1..0c8a57a 100644 --- a/src/timer/instance-status.c +++ b/src/timer/instance-status.c @@ -3,6 +3,19 @@ #include +/** + * 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 4a8a8dd..baa6bec 100644 --- 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 365956c..c436a21 100644 --- a/src/timer/user-instance.c +++ b/src/timer/user-instance.c @@ -10,6 +10,19 @@ #include #include +/** + * 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;