rawmidi; fulfill documentation for ALSARawmidi

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

diff --git a/doc/reference/rawmidi/alsarawmidi-docs.xml b/doc/reference/rawmidi/alsarawmidi-docs.xml
index 284556c4ea90c9f926e198e97d29b6893abe3346..392bbeb92fb00a34255dcf13850fdf29da19e54b 100644 (file)
--- a/doc/reference/rawmidi/alsarawmidi-docs.xml
+++ b/doc/reference/rawmidi/alsarawmidi-docs.xml
@@ -12,6 +12,15 @@
     </releaseinfo>
     </bookinfo>
 
+    <chapter id="introduction">
+        <title>Introduction</title>
+        <para>This library is designed for applications to manipulate ALSA
+        Rawmidi character device and operate rawmidi functionality abstracted
+        as a pair of streams and substream. ALSARawmidiStreamPair represents
+        the pair of streams. It holds file descriptor and creates GSource for
+        event dispathing by GLib's GMainContext/GMainLoop.</para>
+    </chapter>
+
     <chapter id="alsarawmidi-enumerations">
         <title>ALSARawmidi enumerations</title>
         <xi:include href="xml/alsarawmidi-enum-types.xml"/>

diff --git a/src/rawmidi/query.c b/src/rawmidi/query.c
index b5670e9937455af4f51b7a5230947f790fce52c0..b478278df3e40d07f55f6d8c8ae396b6d81b6ca2 100644 (file)
--- a/src/rawmidi/query.c
+++ b/src/rawmidi/query.c
@@ -12,6 +12,13 @@
 
 #include <libudev.h>
 
+/**
+ * SECTION: query
+ * @Title: Global functions in ALSARawmidi
+ * @Short_description: Global functions available without holding any file
+ *                     descriptor
+ */
+
 // For error reporting.
 G_DEFINE_QUARK("alsarawmidi-error", alsarawmidi_error)
 

diff --git a/src/rawmidi/stream-pair.c b/src/rawmidi/stream-pair.c
index 218b3cb86390e98a7fe089da601a9e8ff53492d6..41d41cfc11fdf743b58827e9ee9b744248382a3d 100644 (file)
--- a/src/rawmidi/stream-pair.c
+++ b/src/rawmidi/stream-pair.c
@@ -11,6 +11,29 @@
 #include <unistd.h>
 #include <sys/ioctl.h>
 
+/**
+ * SECTION: stream-pair
+ * @Title: ALSARawmidiStreamPair
+ * @Short_description: A GObject-derived object to represent a pair of Rawmidi
+ *                     stream.
+ *
+ * A #ALSARawmidiStreamPair is a GObject-derived object to represent a pair
+ * of Rawmidi stream to which substreams are attached. The substream is pointed
+ * by the combination of the numerical ID of device, subdevice, and direction.
+ * When the call of alsarawmidi_stream_pair_open() with the combination,
+ * corresponding substreams are attached to the object. Then the object maintains
+ * file descriptor till object destruction. The call of
+ * alsarawmidi_stream_pair_create_source() returns the instance of GSource. Once
+ * attached to the GSource, GMainContext/GMainLoop is available as event
+ * dispatcher. The 'handle-messages' GObject signal is emit in the event
+ * dispatcher to notify the intermediate buffer of capture substream has
+ * available messages. The call of alsarawmidi_stream_pair_read_from_substream()
+ * fills the given buffer with the available messages. The call of
+ * alsarawmidi_stream_pair_write_to_substream() write messages in the given
+ * buffer into the intermediate buffer of playback substream. The call of
+ * alsarawmidi_stream_pair_get_substream_status() is available to check the
+ * space in the intermediate buffer according to direction argument.
+ */
 struct _ALSARawmidiStreamPairPrivate {
     int fd;
     char *devnode;

diff --git a/src/rawmidi/substream-info.c b/src/rawmidi/substream-info.c
index 3e8feecbc762f0a6ae44f45d9039e338b443135b..0c4e47b78093ba0d2e9bcd3caed27b5adcf97c06 100644 (file)
--- a/src/rawmidi/substream-info.c
+++ b/src/rawmidi/substream-info.c
@@ -1,6 +1,19 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: substream-info
+ * @Title: ALSARawmidiSubstreamInfo
+ * @Short_description: A GObject-derived object to represent information of
+ *                     substream
+ *
+ * A #ALSARawmidiSubstreamInfo is a GObject-derived object to represent
+ * information of substream attached to the pair of streams. The call of
+ * alsarawmidi_stream_pair_get_substream_info() or
+ * alsarawmidi_get_substream_info() return the instance of object.
+ *
+ * The object wraps 'struct snd_rawmidi_info' in UAPI of Linux sound subsystem.
+ */
 struct _ALSARawmidiSubstreamInfoPrivate {
     struct snd_rawmidi_info info;
 };

diff --git a/src/rawmidi/substream-params.c b/src/rawmidi/substream-params.c
index bfeb43d35417ea77599f03efe0df03933e80768b..04f900b16ffbe095265664015c2a6d6ebb57eab2 100644 (file)
--- a/src/rawmidi/substream-params.c
+++ b/src/rawmidi/substream-params.c
@@ -3,6 +3,19 @@
 
 #include <unistd.h>
 
+/**
+ * SECTION: substream-params
+ * @Title: ALSARawmidiSubstreamParams
+ * @Short_description: A GObject-derived object to represent parameters of
+ *                     substream.
+ *
+ * A #ALSARawmidiSubstreamParams is a GObject-derived object to represent
+ * parameters of substream attached to the pair of streams. The call of
+ * alsarawmidi_stream_pair_set_substream_params() requires the instance of
+ * object.
+ *
+ * The object wraps 'struct snd_rawmidi_params' in UAPI of Linux sound subsystem.
+ */
 struct _ALSARawmidiSubstreamParamsPrivate {
     struct snd_rawmidi_params params;
 };

diff --git a/src/rawmidi/substream-status.c b/src/rawmidi/substream-status.c
index bcebc0aff6409d3c4f664f07b7e62162ef14892b..6dca740d7f60b71cc6481075f31ebc678f8e35de 100644 (file)
--- a/src/rawmidi/substream-status.c
+++ b/src/rawmidi/substream-status.c
@@ -1,6 +1,18 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 #include "privates.h"
 
+/**
+ * SECTION: substream-status
+ * @Title: ALSARawmidiSubstreamStatus
+ * @Short_description: A GObject-derived object to represent status of substream
+ *
+ * A #ALSARawmidiSubstreamStatus is a GObject-derived object to represent status
+ * of substream attached to the pair of stream. The call of
+ * alsarawmidi_stream_pair_get_substream_status() returns the instance of
+ * object.
+ *
+ * The object wraps 'struct snd_rawmidi_status' in UAPI of Linux sound subsystem.
+ */
 struct _ALSARawmidiSubstreamStatusPrivate {
     struct snd_rawmidi_status status;
 };