From: Takashi Sakamoto Date: Sat, 6 Jun 2020 08:35:12 +0000 (+0900) Subject: seq: fulfill documentation for ALSASeq X-Git-Tag: v0.1.0~138 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=d04ea4126fd001189246b8c9817e64b0e95a925c;p=alsa-gobject.git seq: fulfill documentation for ALSASeq Signed-off-by: Takashi Sakamoto --- diff --git a/doc/reference/seq/alsaseq-docs.xml b/doc/reference/seq/alsaseq-docs.xml index dbe42b0..6e9ea9d 100644 --- a/doc/reference/seq/alsaseq-docs.xml +++ b/doc/reference/seq/alsaseq-docs.xml @@ -12,6 +12,15 @@ + + Introduction + This library is designed for applications to manipulate ALSA + sequencer character device and operate its functionality abstracted. + as user client, port, and event. ALSASeqUserClient represent the user + client. It holds file descriptor and creates GSource for event + dispatching by GLib's GMainContext/GMainLoop. + + ALSASeq enumerations diff --git a/src/seq/addr.c b/src/seq/addr.c index a4a1d56..a4d7d06 100644 --- a/src/seq/addr.c +++ b/src/seq/addr.c @@ -1,6 +1,16 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "addr.h" +/** + * SECTION: addr + * @Title: ALSASeqAddr + * @Short_description: A boxed object to represent address in ALSA Sequencer. + * + * A #ALSASeqAddr is a boxed object to represent address in ALSA Sequencer. The + * address consists of two parts; the numerical ID of client and port. + * + * The object wraps 'struct snd_seq_addr' in UAPI of Linux sound subsystem. + */ ALSASeqAddr *seq_addr_copy(const ALSASeqAddr *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/client-info.c b/src/seq/client-info.c index fa8d281..7996ad2 100644 --- a/src/seq/client-info.c +++ b/src/seq/client-info.c @@ -3,6 +3,19 @@ #include +/** + * SECTION: client-info + * @Title: ALSASeqClientInfo + * @Short_description: A GObject-derived object to represent information of + * client. + * + * A #ALSASeqClientInfo is a GObject-derived object to represent information of + * client. The call of alsaseq_get_client_info() returns the instance of object. + * The call of alsaseq_user_client_set_info() and alsaseq_user_client_get_info() + * require the instance of object. + * + * The object wraps 'struct snd_seq_client_info' in UAPI of Linux sound subsystem. + */ struct _ALSASeqClientInfoPrivate { struct snd_seq_client_info info; }; diff --git a/src/seq/client-pool.c b/src/seq/client-pool.c index 6776b25..a8c46c0 100644 --- a/src/seq/client-pool.c +++ b/src/seq/client-pool.c @@ -1,6 +1,19 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: client-pool + * @Title: ALSASeqClientPool + * @Short_description: A GObject-derived object to represent information of + * pool owned by client. + * + * A #ALSASeqClientPool is a GObject-derived object to represent information of + * pool owned by client. The call of alsaseq_get_client_pool() returns the + * instance of object. The call of alsaseq_user_client_set_pool() and + * alsaseq_user_client_get_pool() require the instance of object. + * + * The object wraps 'struct snd_seq_client_pool' in UAPI of Linux sound subsystem. + */ struct _ALSASeqClientPoolPrivate { struct snd_seq_client_pool pool; }; diff --git a/src/seq/event-data-connect.c b/src/seq/event-data-connect.c index 65d7175..44e3b1e 100644 --- a/src/seq/event-data-connect.c +++ b/src/seq/event-data-connect.c @@ -1,6 +1,17 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "event-data-connect.h" +/** + * SECTION: event-data-connect + * @Title: ALSASeqEventDataConnect + * @Short_description: A boxed object to represent data of connect event + * + * A #ALSASeqEventDataConnect is a boxed object to represent data of connect + * event. The instance of object is one of data properties in + * #ALSASeqEventFixed. + * + * The object wraps 'struct snd_seq_connect' in UAPI of Linux sound subsystem. + */ ALSASeqEventDataConnect *seq_event_data_connect_copy(const ALSASeqEventDataConnect *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/event-data-ctl.c b/src/seq/event-data-ctl.c index 3e3a9f7..266abf4 100644 --- a/src/seq/event-data-ctl.c +++ b/src/seq/event-data-ctl.c @@ -1,6 +1,17 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "event-data-ctl.h" +/** + * SECTION: event-data-ctl + * @Title: ALSASeqEventDataCtl + * @Short_description: A boxed object to represent data of control event + * + * A #ALSASeqEventDataCtl is a boxed object to represent data of control + * event. The instance of object is one of data properties in + * #ALSASeqEventFixed. + * + * The object wraps 'struct snd_seq_ev_ctrl' in UAPI of Linux sound subsystem. + */ ALSASeqEventDataCtl *seq_event_data_ctl_copy(const ALSASeqEventDataCtl *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/event-data-note.c b/src/seq/event-data-note.c index 3f672db..3779638 100644 --- a/src/seq/event-data-note.c +++ b/src/seq/event-data-note.c @@ -1,6 +1,16 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "event-data-note.h" +/** + * SECTION: event-data-note + * @Title: ALSASeqEventDataNote + * @Short_description: A boxed object to represent data of note event + * + * A #ALSASeqEventDataNote is a boxed object to represent data of note event. + * The instance of object is one of data properties in #ALSASeqEventFixed. + * + * The object wraps 'struct snd_seq_ev_note' in UAPI of Linux sound subsystem. + */ ALSASeqEventDataNote *seq_event_data_note_copy(const ALSASeqEventDataNote *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/event-data-queue.c b/src/seq/event-data-queue.c index ebf5fb8..5dad16b 100644 --- a/src/seq/event-data-queue.c +++ b/src/seq/event-data-queue.c @@ -1,6 +1,17 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "event-data-queue.h" +/** + * SECTION: event-data-queue + * @Title: ALSASeqEventDataQueue + * @Short_description: A boxed object to represent data of queue event + * + * A #ALSASeqEventDataQueue is a boxed object to represent data of queue event. + * The instance of object is one of data properties in #ALSASeqEventFixed. + * + * The object wraps 'struct snd_seq_ev_queue_control' in UAPI of Linux sound + * subsystem. + */ ALSASeqEventDataQueue *seq_event_data_queue_copy(const ALSASeqEventDataQueue *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/event-data-result.c b/src/seq/event-data-result.c index f0eae91..6cf376a 100644 --- a/src/seq/event-data-result.c +++ b/src/seq/event-data-result.c @@ -1,6 +1,17 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "event-data-result.h" +/** + * SECTION: event-data-result + * @Title: ALSASeqEventDataResult + * @Short_description: A boxed object to represent data of result event + * + * A #ALSASeqEventDataResult is a boxed object to represent data of result + * event. The instance of object is one of data properties in + * #ALSASeqEventFixed. + * + * The object wraps 'struct snd_seq_result' in UAPI of Linux sound subsystem. + */ ALSASeqEventDataResult *seq_event_data_result_copy(const ALSASeqEventDataResult *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/event-fixed.c b/src/seq/event-fixed.c index 436a5d2..f5355b4 100644 --- a/src/seq/event-fixed.c +++ b/src/seq/event-fixed.c @@ -4,6 +4,16 @@ #include +/** + * SECTION: event-fixed + * @Title: ALSASeqEventFixed + * @Short_description: A GObject-derived object to represent event with the + * various kind of fixed-size data. + * + * A #ALSASeqEventFixed is a GObject-derived object to represent event with the + * various kind of fixed-size data. The object has several properties to access + * to the data. The object inherits properties and methods from #ALSASeqEvent. + */ G_DEFINE_TYPE(ALSASeqEventFixed, alsaseq_event_fixed, ALSASEQ_TYPE_EVENT) enum seq_event_fixed_prop_type { diff --git a/src/seq/event-variable.c b/src/seq/event-variable.c index 2331706..e76b3aa 100644 --- a/src/seq/event-variable.c +++ b/src/seq/event-variable.c @@ -4,6 +4,17 @@ #include +/** + * SECTION: event-variable + * @Title: ALSASeqEventVariable + * @Short_description: A GObject-derived object to represent event with the + * various kind of variable-size data. + * + * A #ALSASeqEventVariable is a GObject-derived object to represent event with + * the various kind of variable-size data. The object has accessor methods for + * the variable-size data. + * The object inherits properties and methods from #ALSASeqEvent. + */ struct _ALSASeqEventVariablePrivate { void *data; }; diff --git a/src/seq/event.c b/src/seq/event.c index dd49584..6ad2999 100644 --- a/src/seq/event.c +++ b/src/seq/event.c @@ -3,6 +3,17 @@ #include +/** + * SECTION: event + * @Title: ALSASeqEvent + * @Short_description: A GObject-derived abstract object to represent any event + * + * A #ALSASeqEvent is a GObject-derived abstract object to represent common + * properties and method for any event. Applications can use derived object; + * #ALSASeqEventFixed and #ALSASeqEventVariable. + * + * The object wraps 'struct snd_seq_event' in UAPI of Linux sound subsystem. + */ struct _ALSASeqEventPrivate { struct snd_seq_event ev; }; diff --git a/src/seq/port-info.c b/src/seq/port-info.c index 35dd698..73c7390 100644 --- a/src/seq/port-info.c +++ b/src/seq/port-info.c @@ -1,6 +1,18 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: port-info + * @Title: ALSASeqPortInfo + * @Short_description: A GObject-derived object to represent information of port + * + * A #ALSASeqPortInfo is a GObject-derived object to represent information of + * port. The call of alsaseq_get_port_info() returns the instance of object. + * The call of alsaseq_user_client_create_port() and + * alsaseq_user_client_update_port() requires the instance of object. + * + * The object wraps 'struct snd_port_info' in UAPI of Linux sound subsystem. + */ struct _ALSASeqPortInfoPrivate { struct snd_seq_port_info info; }; diff --git a/src/seq/query.c b/src/seq/query.c index fbc2411..0844b8f 100644 --- a/src/seq/query.c +++ b/src/seq/query.c @@ -12,6 +12,13 @@ #include +/** + * SECTION: query + * @Title: Global functions in ALSASeq + * @Short_description: Global functions available without holding any file + * descriptor + */ + // For error handling. G_DEFINE_QUARK("alsaseq-error", alsaseq_error) diff --git a/src/seq/queue-info.c b/src/seq/queue-info.c index 8f1eaf9..c7f0dc8 100644 --- a/src/seq/queue-info.c +++ b/src/seq/queue-info.c @@ -1,6 +1,20 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: queue-info + * @Title: ALSASeqQueueInfo + * @Short_description: A GObject-derived object to represent information of + * queue + * + * A #ALSASeqQueueInfo is a GObject-derived object to represent information of + * queue. The call of alsaseq_get_queue_info_by_id() and + * alsaseq_get_queue_info_by_name() returns the instance of object. The call of + * alsaseq_user_client_create_queue() and alsaseq_user_client_update_queue() + * requires the instance of object. + * + * The object wraps 'struct snd_seq_queue_info' in UAPI of Linux sound subsystem. + */ struct _ALSASeqQueueInfoPrivate { struct snd_seq_queue_info info; }; diff --git a/src/seq/queue-status.c b/src/seq/queue-status.c index 19d2eb4..5a864a3 100644 --- a/src/seq/queue-status.c +++ b/src/seq/queue-status.c @@ -1,6 +1,17 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: queue-status + * @Title: ALSASeqQueueStatus + * @Short_description: A GObject-derived object to represent status of queue + * + * A #ALSASeqQueueStatus is a GObject-derived object to represent status of + * queue. The call of alsaseq_get_queue_status() returns the instance of object. + * + * The object wraps 'struct snd_seq_queue_status' in UAPI of Linux sound + * subsystem. + */ struct _ALSASeqQueueStatusPrivate { struct snd_seq_queue_status status; }; diff --git a/src/seq/queue-tempo.c b/src/seq/queue-tempo.c index 2c45daf..54b1c33 100644 --- a/src/seq/queue-tempo.c +++ b/src/seq/queue-tempo.c @@ -1,6 +1,16 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: queue-tempo + * @Title: ALSASeqQueueTempo + * @Short_description: A GObject-derived object to represent tempo of queue + * + * A #ALSASeqQueueTempo is a GObject-derived object to represent tempo of queue. + * The call of alsaseq_get_queue_status() returns the instance of object. + * + * The object wraps 'struct snd_seq_queue_tempo' in UAPI of Linux sound subsystem. + */ struct _ALSASeqQueueTempoPrivate { struct snd_seq_queue_tempo tempo; }; diff --git a/src/seq/queue-timer-alsa.c b/src/seq/queue-timer-alsa.c index 16aeb4f..6583201 100644 --- a/src/seq/queue-timer-alsa.c +++ b/src/seq/queue-timer-alsa.c @@ -2,6 +2,17 @@ #include "queue-timer-alsa.h" #include "privates.h" +/** + * SECTION: queue-timer-alsa + * @Title: ALSASeqQueueTimerAlsa + * @Short_description: A GObject-derived object to represent timer instance for + * queue + * + * A #ALSASeqQueueTimerAlsa is a GObject-derived object to represent timer + * instance for queue. The instance belongs to ALSA timer functionality and is + * pointed by the identifier as property of the object. The object inherits + * properties and methods from #ALSASeqQueueTimer. + */ G_DEFINE_TYPE(ALSASeqQueueTimerAlsa, alsaseq_queue_timer_alsa, ALSASEQ_TYPE_QUEUE_TIMER) enum seq_queue_timer_alsa_prop_type { diff --git a/src/seq/queue-timer.c b/src/seq/queue-timer.c index 09e7b09..887e388 100644 --- a/src/seq/queue-timer.c +++ b/src/seq/queue-timer.c @@ -3,6 +3,18 @@ #include +/** + * SECTION: queue-timer + * @Title: ALSASeqQueueTimer + * @Short_description: A GObject-derived abstract object to represent timer for + * queue + * + * A #ALSASeqQueueTimer is a GObject-derived abstract object to represent common + * properties and methods of timer for queue. Applications can use derived + * object; ALSASeqQueueTimerAlsa. + * + * The object wraps 'struct snd_seq_queue_timer' in UAPI of Linux sound subsystem. + */ struct _ALSASeqQueueTimerPrivate { struct snd_seq_queue_timer timer; }; diff --git a/src/seq/remove-filter.c b/src/seq/remove-filter.c index ecb8d7c..eeee419 100644 --- a/src/seq/remove-filter.c +++ b/src/seq/remove-filter.c @@ -4,6 +4,20 @@ #include +/** + * SECTION: remove-filter + * @Title: ALSASeqRemoveFilter + * @Short_description: A boxed object to represent filter to remove scheduled + * event in queue + * + * A #ALSASeqRemoveFilter is a boxed object to represent filter to remove + * scheduled event in queue. The call of alsaseq_user_client_remove_events() + * requires the instance of object. In the object, data shares the same storage, + * thus it's not possible to use several purposes. + * + * The object wraps 'struct snd_seq_remove_events' in UAPI of Linux sound + * subsystem. + */ ALSASeqRemoveFilter *seq_remove_filter_copy(const ALSASeqRemoveFilter *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/subscribe-data.c b/src/seq/subscribe-data.c index 4ef47b5..3515187 100644 --- a/src/seq/subscribe-data.c +++ b/src/seq/subscribe-data.c @@ -1,6 +1,20 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: subscribe-data + * @Title: ALSASeqSubscribeData + * @Short_description: A GObject-derived object to represent data for + * subscription between ports. + * + * A #ALSASeqSubscribeData is a GObject-derived object to represent data for + * subscription between a pair of ports. The call of + * alsaseq_get_subscription_list() returns the list of data. The call of + * alsaseq_user_client_operate_subscription() requires the instance of object. + * + * The object wraps 'struct snd_seq_port_subscribe' in UAPI of Linux sound + * subsystem. + */ struct _ALSASeqSubscribeDataPrivate { struct snd_seq_port_subscribe data; }; diff --git a/src/seq/system-info.c b/src/seq/system-info.c index 147952e..cc4821e 100644 --- a/src/seq/system-info.c +++ b/src/seq/system-info.c @@ -1,6 +1,18 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "privates.h" +/** + * SECTION: system-info + * @Title: ALSASeqSystemInfo + * @Short_description: A GObject-derived object to represent information of + * ALSA Sequencer + * + * A #ALSASeqSystemInfo is a GObject-derived object to represent information of + * ALSA Sequencer. The call of alsaseq_get_system_info() returns the instance of + * object. + * + * The object wraps 'struct snd_seq_system_info' in UAPI of Linux sound subsystem. + */ struct _ALSASeqSystemInfoPrivate { struct snd_seq_system_info info; }; diff --git a/src/seq/tstamp.c b/src/seq/tstamp.c index 0066a67..36de92a 100644 --- a/src/seq/tstamp.c +++ b/src/seq/tstamp.c @@ -1,6 +1,16 @@ // SPDX-License-Identifier: LGPL-3.0-or-later #include "tstamp.h" +/** + * SECTION: tstamp + * @Title: ALSASeqTstamp + * @Short_description: A boxed object to represent timestamp + * + * A #ALSASeqTstamp is a boxed object to represent timestamp. The object shares + * storage for two types of time; tick time and real time. + * + * The object wraps 'struct snd_seq_timestamp' in UAPI of Linux sound subsystem. + */ ALSASeqTstamp *seq_tstamp_copy(const ALSASeqTstamp *self) { return g_memdup(self, sizeof(*self)); diff --git a/src/seq/user-client.c b/src/seq/user-client.c index 04052c1..b60ecf2 100644 --- a/src/seq/user-client.c +++ b/src/seq/user-client.c @@ -10,6 +10,22 @@ #include #include +/** + * SECTION: user-client + * @Title: ALSASeqUserClient + * @Short_description: A GObject-derived object to represent user client + * + * A #ALSASeqUserClient is a GObject-derived object to represent user client. + * Any port can be added to the client as destination or source for any event. + * + * When the call of alsaseq_user_client_open(), the object maintain file + * descriptor till object destruction. The call of + * alsaseq_user_client_create_source() returns the instance of GSource. Once + * attached to the GSource, GMainContext/GMainLoop is available as event + * dispatcher. The #handle-event GObject signal is emitted in the event + * dispatcher to notify the event. The call of + * alsaseq_user_client_schedule_event() schedules event with given parameters. + */ struct _ALSASeqUserClientPrivate { int fd; int client_id;