doc: annotate error domain available in gi-docgen 2023.1

The gi-docgen 2023.1 includes fix to deal with error domain. This commit adopts the fix towards better documentation. Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
takaswie · Oct 29, 2023 · 9daef10 · 9daef10
1 parent 41b3ddf
commit 9daef10
Show file tree

Hide file tree

Showing 9 changed files with 54 additions and 31 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -16,9 +16,21 @@ jobs:
         dnf -y install gi-docgen python3-gobject
     - name: Checkout repository.
       uses: actions/checkout@v3
-    - name: Create hinawa.wrap in subproject directory
+    - name: Create gi-docgen.wrap in subproject directory
       run: |
         mkdir subprojects
+        cat > subprojects/gi-docgen.wrap << EOF
+        [wrap-git]
+        directory = gi-docgen
+        url = https://gitlab.gnome.org/GNOME/gi-docgen.git
+        revision = 2023.1
+        depth = 1
+        
+        [provide]
+        program_names = gi-docgen
+        EOF
+    - name: Create hinawa.wrap in subproject directory
+      run: |
         cat > subprojects/hinawa.wrap << EOF
         [wrap-git]
         directory = libhinawa
@@ -59,9 +71,21 @@ jobs:
         DEBIAN_FRONTEND=noninteractive apt-get install -y gi-docgen python3-gi
     - name: Checkout repository.
       uses: actions/checkout@v3
-    - name: Create hinawa.wrap in subproject directory
+    - name: Create gi-docgen.wrap in subproject directory
       run: |
         mkdir subprojects
+        cat > subprojects/gi-docgen.wrap << EOF
+        [wrap-git]
+        directory = gi-docgen
+        url = https://gitlab.gnome.org/GNOME/gi-docgen.git
+        revision = 2023.1
+        depth = 1
+        
+        [provide]
+        program_names = gi-docgen
+        EOF
+    - name: Create hinawa.wrap in subproject directory
+      run: |
         cat > subprojects/hinawa.wrap << EOF
         [wrap-git]
         directory = libhinawa

diff --git a/README.rst b/README.rst
@@ -53,7 +53,7 @@ Requirements to build
 - Meson 0.56.0 or later
 - Ninja
 - PyGObject (optional to run unit tests)
-- gi-docgen (optional to generate API documentation)
+- gi-docgen 2023.1 or later (optional to generate API documentation)
 
 How to build
 ============

diff --git a/doc/meson.build b/doc/meson.build
@@ -13,7 +13,7 @@ doc_toml = configure_file(
 )
 
 dependency('gi-docgen',
-  version: '>= 2021.8',
+  version: '>= 2023.1',
   fallback: ['gi-docgen', 'dummy_dep'],
 )
 gidocgen = find_program('gi-docgen')

diff --git a/src/fw_iso_ctx.c b/src/fw_iso_ctx.c
@@ -16,16 +16,15 @@ G_DEFINE_INTERFACE(HinokoFwIsoCtx, hinoko_fw_iso_ctx, G_TYPE_OBJECT)
 /**
  * hinoko_fw_iso_ctx_error_quark:
  *
- * Return the [alias@GLib.Quark] for error domain of [struct@GLib.Error] which has code in
- * Hinoko.FwIsoCtxError.
+ * Return the [alias@GLib.Quark] for [struct@GLib.Error] which has code in [error@FwIsoCtxError].
  *
  * Returns: A [alias@GLib.Quark].
  */
 G_DEFINE_QUARK(hinoko-fw-iso-ctx-error-quark, hinoko_fw_iso_ctx_error)
 
 /**
  * hinoko_fw_iso_ctx_error_to_label:
- * @code: One of Hinoko.FwIsoCtxError.
+ * @code: One of [error@FwIsoCtxError].
  * @label: (out) (transfer none): The label of error code.
  *
  * Retrieve the label of error code.

diff --git a/src/fw_iso_resource.c b/src/fw_iso_resource.c
@@ -16,16 +16,16 @@ G_DEFINE_INTERFACE(HinokoFwIsoResource, hinoko_fw_iso_resource, G_TYPE_OBJECT)
 /**
  * hinoko_fw_iso_resource_error_quark:
  *
- * Return the [alias@GLib.Quark] for error domain of [struct@GLib.Error] which has code in
- * Hinoko.FwIsoResourceError.
+ * Return the [alias@GLib.Quark] for [struct@GLib.Error] with which has code in
+ * [error@FwIsoResourceError].
  *
  * Returns: A [alias@GLib.Quark].
  */
 G_DEFINE_QUARK(hinoko-fw-iso-resource-error-quark, hinoko_fw_iso_resource_error)
 
 /**
  * hinoko_fw_iso_resource_error_to_label:
- * @code: One of Hinoko.FwIsoResourceError.
+ * @code: One of [error@FwIsoResourceError].
  * @label: (out) (transfer none): The label of error code.
  *
  * Retrieve the label of error code.
@@ -81,7 +81,7 @@ static void hinoko_fw_iso_resource_default_init(HinokoFwIsoResourceInterface *if
 	 * @channel: The deallocated channel number.
 	 * @bandwidth: The deallocated amount of bandwidth.
 	 * @error: (transfer none) (nullable) (in): A [struct@GLib.Error]. Error can be generated
-	 *	   with domain of Hinoko.FwIsoResourceError and its EVENT code.
+	 *	   with domain of [error@FwIsoResourceError] and its EVENT code.
 	 *
 	 * Emitted when allocation of isochronous resource finishes.
 	 *
@@ -102,7 +102,7 @@ static void hinoko_fw_iso_resource_default_init(HinokoFwIsoResourceInterface *if
 	 * @channel: The deallocated channel number.
 	 * @bandwidth: The deallocated amount of bandwidth.
 	 * @error: (transfer none) (nullable) (in): A [struct@GLib.Error]. Error can be generated
-	 *	   with domain of Hinoko.FwIsoResourceError and its EVENT code.
+	 *	   with domain of [error@FwIsoResourceError] and its EVENT code.
 	 *
 	 * Emitted when deallocation of isochronous resource finishes.
 	 *
@@ -124,8 +124,8 @@ static void hinoko_fw_iso_resource_default_init(HinokoFwIsoResourceInterface *if
  * @path: A path of any Linux FireWire character device.
  * @open_flag: The flag of open(2) system call. O_RDONLY is forced to fulfil
  *	       internally.
- * @error: A [struct@GLib.Error]. Error can be generated with two domains; GLib.FileError
- *	   and Hinoko.FwIsoResourceError.
+ * @error: A [struct@GLib.Error]. Error can be generated with two domains; [error@GLib.FileError]
+ *	   and [error@FwIsoResourceError].
  *
  * Open Linux FireWire character device to delegate any request for isochronous
  * resource management to Linux FireWire subsystem.
@@ -174,7 +174,7 @@ gboolean hinoko_fw_iso_resource_create_source(HinokoFwIsoResource *self, GSource
  *			numeric number of isochronous channel to be allocated.
  * @channel_candidates_count: The number of channel candidates.
  * @bandwidth: The amount of bandwidth to be allocated.
- * @error: A [struct@GLib.Error]. Error can be generated with domain of Hinoko.FwIsoResourceError
+ * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwIsoResourceError]
  *	   as well as domain depending on each implementation.
  *
  * Initiate allocation of isochronous resource without any wait. One of the candidates is actually
@@ -209,7 +209,7 @@ gboolean hinoko_fw_iso_resource_allocate_async(HinokoFwIsoResource *self,
  * @channel_candidates_count: The number of channel candidates.
  * @bandwidth: The amount of bandwidth to be allocated.
  * @timeout_ms: The timeout to wait for allocated event.
- * @error: A [struct@GLib.Error]. Error can be generated with domain of Hinoko.FwIsoResourceError
+ * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwIsoResourceError]
  *	   as well as domain depending on each implementation.
  *
  * Initiate allocation of isochronous resource and wait for [signal@FwIsoResource::allocated]

diff --git a/src/fw_iso_resource.h b/src/fw_iso_resource.h
@@ -22,8 +22,8 @@ struct _HinokoFwIsoResourceInterface {
 	 * @self: A [iface@FwIsoResource].
 	 * @path: A path of any Linux FireWire character device.
 	 * @open_flag: The flag of open(2) system call. O_RDONLY is forced to fulfil internally.
-	 * @error: A [struct@GLib.Error]. Error can be generated with two domains; GLib.FileError
-	 *	   and Hinoko.FwIsoResourceError.
+	 * @error: A [struct@GLib.Error]. Error can be generated with two domains;
+	 *	   [error@GLib.FileError] and [error@FwIsoResourceError].
 	 *
 	 * Virtual function to open Linux FireWire character device to delegate any request for
 	 * isochronous resource management to Linux FireWire subsystem.
@@ -75,7 +75,7 @@ struct _HinokoFwIsoResourceInterface {
 	 * @channel: The deallocated channel number.
 	 * @bandwidth: The deallocated amount of bandwidth.
 	 * @error: (transfer none) (nullable) (in): A [struct@GLib.Error]. Error can be generated
-	 *	   with domain of Hinoko.FwIsoResourceError and its EVENT code.
+	 *	   with domain of [error@FwIsoResourceError] and its EVENT code.
 	 *
 	 * Closure for the [signal@FwIsoResource::allocated] signal.
 	 *
@@ -90,7 +90,7 @@ struct _HinokoFwIsoResourceInterface {
 	 * @channel: The deallocated channel number.
 	 * @bandwidth: The deallocated amount of bandwidth.
 	 * @error: (transfer none) (nullable) (in): A [struct@GLib.Error]. Error can be generated
-	 *	   with domain of Hinoko.FwIsoResourceError and its EVENT code.
+	 *	   with domain of [error@FwIsoResourceError] and its EVENT code.
 	 *
 	 * Closure for the [signal@FwIsoResource::deallocated] signal.
 	 *

diff --git a/src/fw_iso_resource_auto.c b/src/fw_iso_resource_auto.c
@@ -30,15 +30,15 @@ G_DEFINE_TYPE_WITH_CODE(HinokoFwIsoResourceAuto, hinoko_fw_iso_resource_auto, G_
  * hinoko_fw_iso_resource_auto_error_quark:
  *
  * Return the [alias@GLib.Quark] for error domain of [struct@GLib.Error] which has code in
- * Hinoko.FwIsoResourceAutoError.
+ * [error@FwIsoResourceAutoError].
  *
  * Returns: A [alias@GLib.Quark].
  */
 G_DEFINE_QUARK(hinoko-fw-iso-resource-auto-error-quark, hinoko_fw_iso_resource_auto_error)
 
 /**
  * fw_iso_resource_auto_error_to_label:
- * @code: One of Hinoko.FwIsoResourceAutoError.
+ * @code: One of [error@FwIsoResourceAutoError].
  * @label: (out) (transfer none): The label of error code.
  *
  * Retrieve the label of error code.
@@ -362,8 +362,8 @@ HinokoFwIsoResourceAuto *hinoko_fw_iso_resource_auto_new()
 /**
  * hinoko_fw_iso_resource_auto_deallocate_async:
  * @self: A [class@FwIsoResourceAuto]
- * @error: A [struct@GLib.Error]. Error can be generated with domain of
- *	   Hinoko.FwIsoResourceError, and Hinoko.FwIsoResourceAutoError.
+ * @error: A [struct@GLib.Error]. Error can be generated with domains of [error@FwIsoResourceError],
+ *	   and [error@FwIsoResourceAutoError].
  *
  * Initiate deallocation of isochronous resource. When the deallocation is done,
  * [signal@FwIsoResource::deallocated] signal is emit to notify the result, channel, and bandwidth.
@@ -415,8 +415,8 @@ gboolean hinoko_fw_iso_resource_auto_deallocate_async(HinokoFwIsoResourceAuto *s
  * hinoko_fw_iso_resource_auto_deallocate_sync:
  * @self: A [class@FwIsoResourceAuto]
  * @timeout_ms: The timeout to wait for allocated event by milli second unit.
- * @error: A [struct@GLib.Error]. Error can be generated with domain of
- *	   Hinoko.FwIsoResourceError, and Hinoko.FwIsoResourceAutoError.
+ * @error: A [struct@GLib.Error]. Error can be generated with domains of [error@FwIsoResourceError],
+ *	   and [error@FwIsoResourceAutoError].
  *
  * Initiate deallocation of isochronous resource. When the deallocation is done,
  * [signal@FwIsoResource::deallocated] signal is emit to notify the result, channel, and bandwidth.

diff --git a/src/fw_iso_resource_once.c b/src/fw_iso_resource_once.c
@@ -207,7 +207,7 @@ HinokoFwIsoResourceOnce *hinoko_fw_iso_resource_once_new()
  * @self: A [class@FwIsoResourceOnce].
  * @channel: The channel number to be deallocated.
  * @bandwidth: The amount of bandwidth to be deallocated.
- * @error: A [struct@GLib.Error]. Error can be generated with domain of Hinoko.FwIsoResourceError.
+ * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwIsoResourceError].
  *
  * Initiate deallocation of isochronous resource without any wait. When the
  * deallocation finishes, [signal@FwIsoResource::deallocated] signal is emit to notify the result,
@@ -253,7 +253,7 @@ gboolean hinoko_fw_iso_resource_once_deallocate_async(HinokoFwIsoResourceOnce *s
  * @channel: The channel number to be deallocated.
  * @bandwidth: The amount of bandwidth to be deallocated.
  * @timeout_ms: The timeout to wait for deallocated event.
- * @error: A [struct@GLib.Error]. Error can be generated with domain of Hinoko.FwIsoResourceError.
+ * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwIsoResourceError].
  *
  * Initiate deallocation of isochronous resource and wait for [signal@FwIsoResource::deallocated]
  * signal.

diff --git a/src/hinoko_enum_types.h b/src/hinoko_enum_types.h
@@ -67,7 +67,7 @@ typedef enum /*< flags >*/
  * @HINOKO_FW_ISO_RESOURCE_ERROR_TIMEOUT:	No event to the request arrives within timeout.
  * @HINOKO_FW_ISO_RESOURCE_ERROR_EVENT:		Event for the request arrives but includes error code.
  *
- * A set of error code for [iface@FwIsoResource].
+ * A set of error code for operations in [iface@FwIsoResource].
  */
 typedef enum {
 	HINOKO_FW_ISO_RESOURCE_ERROR_FAILED,
@@ -85,7 +85,7 @@ typedef enum {
  * @HINOKO_FW_ISO_RESOURCE_AUTO_ERROR_NOT_ALLOCATED:	The instance is not associated to allocated
  *							isochronous resources.
  *
- * A set of error code for [class@FwIsoResourceAuto].
+ * A set of error code for operations in [class@FwIsoResourceAuto].
  */
 typedef enum {
 	HINOKO_FW_ISO_RESOURCE_AUTO_ERROR_FAILED,
@@ -107,7 +107,7 @@ typedef enum {
  * @HINOKO_FW_ISO_CTX_ERROR_CHUNK_UNREGISTERED:	No chunk registered before starting.
  * @HINOKO_FW_ISO_CTX_ERROR_NO_ISOC_CHANNEL:	No isochronous channel is available.
  *
- * A set of error code for [iface@FwIsoCtx].
+ * A set of error code for operations in [iface@FwIsoCtx].
  */
 typedef enum {
 	HINOKO_FW_ISO_CTX_ERROR_FAILED,