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 <[email protected]>

.github/workflows/build.yml

@@ -8,14 +8,27 @@ jobs:
     container:
       image: fedora:rawhide
     steps:
-    - name: Checkout repository.
-      uses: actions/checkout@v2
     - name: Prepare build environment.
       run: |
         dnf -y upgrade
         dnf -y install @development-tools
         dnf -y install meson gobject-introspection-devel systemd-devel
         dnf -y install gi-docgen python3-gobject
+    - name: Checkout repository.
+      uses: actions/checkout@v2
+    - 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: Initialization for build.
       run: |
         meson --prefix=/tmp. -Ddoc=true -Dwarning_level=3 . build
@@ -41,15 +54,28 @@ jobs:
     container:
       image: ubuntu:latest
     steps:
-    - name: Checkout repository.
-      uses: actions/checkout@v3
     - name: Prepare build environment.
       run: |
         DEBIAN_FRONTEND=noninteractive apt-get update
         DEBIAN_FRONTEND=noninteractive apt-get -y full-upgrade
         DEBIAN_FRONTEND=noninteractive apt-get install -y git build-essential
         DEBIAN_FRONTEND=noninteractive apt-get install -y meson ninja-build libglib2.0-dev gobject-introspection libgirepository1.0-dev
         DEBIAN_FRONTEND=noninteractive apt-get install -y gi-docgen python3-gi
+    - name: Checkout repository.
+      uses: actions/checkout@v2
+    - 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: Initialization for build.
       run: |
         meson --prefix=/tmp. -Ddoc=true -Dwarning_level=3 . build

README.rst

@@ -53,7 +53,7 @@ Requirements to build
 - Meson 0.60.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
 ============

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')

src/fw_fcp.c

@@ -23,7 +23,7 @@
 /**
  * hinawa_fw_fcp_error_quark:
  *
- * Return the [[email protected]] for [[email protected]] which has code in Hinawa.FwFcpError.
+ * Return the [[email protected]] for [[email protected]] which has code in [error@FwFcpError].
  *
  * Since: 2.1
  *
@@ -230,8 +230,8 @@ HinawaFwFcp *hinawa_fw_fcp_new(void)
  *	    The first element is for the isochronous cycle at which the request arrived. The second
  *	    element is for the isochronous cycle at which the response was sent.
  * @timeout_ms: The timeout to wait for response subaction of transaction for command frame.
- * @error: A [[email protected]]. Error can be generated with four domains; Hinoko.FwNodeError and
- *	   Hinoko.FwReqError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@FwNodeError] and
+ *	   [error@FwReqError].
  *
  * Transfer command frame for FCP. When receiving response frame for FCP, [signal@FwFcp::responded]
  * signal is emitted.
@@ -280,8 +280,8 @@ gboolean hinawa_fw_fcp_command_with_tstamp(HinawaFwFcp *self, const guint8 *cmd,
  *	 argument should point to the array and immutable.
  * @cmd_size: The size of array for request in byte unit.
  * @timeout_ms: The timeout to wait for response subaction of transaction for command frame.
- * @error: A [[email protected]]. Error can be generated with four domains; Hinoko.FwNodeError and
- *	   Hinoko.FwReqError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@FwNodeError] and
+ *	   [error@FwReqError].
  *
  * Transfer command frame for FCP. When receiving response frame for FCP, [signal@FwFcp::responded]
  * signal is emitted.
@@ -363,8 +363,8 @@ static void handle_responded_signal(HinawaFwFcp *self, guint generation, guint t
  *	    which the response arrived for the command of FCP transaction. The third element is for
  *	    the isochronous cycle at which the request was sent for the response of FCP transaction.
  * @timeout_ms: The timeout to wait for response transaction since command transactions finishes.
- * @error: A [[email protected]]. Error can be generated with four domains; Hinawa.FwNodeError,
- *	   Hinawa.FwReqError, and Hinawa.FwFcpError.
+ * @error: A [[email protected]]. Error can be generated with thtree domains; [error@FwNodeError],
+ *	   [error@FwReqError], and [error@FwFcpError].
  *
  * Finish the pair of asynchronous transaction for AV/C command and response. The @timeout_ms
  * parameter is used to wait for response transaction since the command transaction is initiated.
@@ -488,8 +488,8 @@ gboolean hinawa_fw_fcp_avc_transaction_with_tstamp(HinawaFwFcp *self,
  * @resp_size: The size of array for response in byte unit. The value of this argument should point to
  *	       the numerical number and mutable.
  * @timeout_ms: The timeout to wait for response transaction since command transactions finishes.
- * @error: A [[email protected]]. Error can be generated with four domains; Hinawa.FwNodeError,
- *	   Hinawa.FwReqError, and Hinawa.FwFcpError.
+ * @error: A [[email protected]]. Error can be generated with three domains; [error@FwNodeError],
+ *	   [error@FwReqError], and [error@FwFcpError].
  *
  * Finish the pair of asynchronous transaction for AV/C command and response. The @timeout_ms
  * parameter is used to wait for response transaction since the command transaction is initiated.
@@ -639,7 +639,7 @@ static HinawaFwRcode handle_requested_signal(HinawaFwResp *resp, HinawaFwTcode t
  * hinawa_fw_fcp_bind:
  * @self: A [class@FwFcp].
  * @node: A [class@FwNode].
- * @error: A [[email protected]]. Error can be generated with domain of Hinawa.FwFcpError.
+ * @error: A [[email protected]]. Error can be generated with domain of [error@FwFcpError].
  *
  * Start to listen to FCP responses.
  *

src/fw_node.c

@@ -41,7 +41,7 @@ G_DEFINE_TYPE_WITH_PRIVATE(HinawaFwNode, hinawa_fw_node, G_TYPE_OBJECT)
 /**
  * hinawa_fw_node_error_quark:
  *
- * Return the [[email protected]] for [[email protected]] with Hinawa.FwNodeError domain.
+ * Return the [[email protected]] for [[email protected]] with [error@FwNodeError] domain.
  *
  * Since: 2.1
  *
@@ -355,8 +355,8 @@ static int update_info(HinawaFwNode *self)
  * @self: A [class@FwNode]
  * @path: A path to Linux FireWire character device
  * @open_flag: The flag of `open(2)` system call. `O_RDONLY` is fulfilled internally.
- * @error: A [[email protected]]. Error can be generated with two domains; GLib.Error and
- *	   Hinawa.FwNodeError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@GLib.FileError]
+ *	   and [error@FwNodeError].
  *
  * Open Linux FireWire character device to operate node in IEEE 1394 bus.
  *
@@ -596,7 +596,7 @@ static void finalize_src(GSource *gsrc)
  * hinawa_fw_node_create_source:
  * @self: A [class@FwNode].
  * @gsrc: (out): A [[email protected]].
- * @error: A [[email protected]]. Error can be generated with domain of Hinawa.FwNodeError.
+ * @error: A [[email protected]]. Error can be generated with domain of [error@FwNodeError].
  *
  * Create [[email protected]] for [[email protected]] to dispatch events for the node on
  * IEEE 1394 bus.

src/fw_req.c

@@ -126,8 +126,8 @@ HinawaFwReq *hinawa_fw_req_new(void)
  *	   transaction.
  * @frame_size: The size of array in byte unit. The value of this argument should point to the
  *		numeric number and mutable for read and lock transaction.
- * @error: A [[email protected]]. Error can be generated with two domains; Hinawa.FwNodeError and
- *	   Hinawa.FwReqError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@FwNodeError] and
+ *	   [error@FwReqError].
  *
  * Execute request subaction of transaction to the given node according to given code. When the
  * response subaction arrives and running event dispatcher reads the contents,
@@ -254,8 +254,8 @@ static void handle_responded_signal(HinawaFwReq *self, HinawaFwRcode rcode, guin
  *	    The second element is for the isochronous cycle at which the response subaction arrived.
  * @timeout_ms: The timeout to wait for the response subaction of transaction since the request
  *		subaction is initiated, in milliseconds.
- * @error: A [[email protected]]. Error can be generated with two domains; Hinawa.FwNodeError and
- *	   Hinawa.FwReqError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@FwNodeError] and
+ *	   [error@FwReqError].
  *
  * Execute request subaction of transaction to the given node according to given code, then wait
  * for response subaction within the given timeout.
@@ -362,8 +362,8 @@ gboolean hinawa_fw_req_transaction_with_tstamp(HinawaFwReq *self, HinawaFwNode *
  *		numerical number and mutable for read and lock transaction.
  * @timeout_ms: The timeout to wait for response subaction of the transaction since request
  *		subaction is initiated, in milliseconds.
- * @error: A [[email protected]]. Error can be generated with two domains; Hinawa.FwNodeError and
- *	   Hinawa.FwReqError.
+ * @error: A [[email protected]]. Error can be generated with two domains; [error@FwNodeError] and
+ *	   [error@FwReqError].
  *
  * Execute request subaction of transaction to the given node according to given code, then wait
  * for response subaction within the value of timeout argument. The function is a thin wrapper to

src/fw_resp.c

@@ -16,7 +16,7 @@
  * hinawa_fw_resp_error_quark:
  *
  * Return the [[email protected]] for error domain of [[email protected]] which has code in
- * Hinawa.FwRespError.
+ * [error@FwRespError].
  *
  * Since: 2.2
  *
@@ -219,8 +219,8 @@ HinawaFwResp *hinawa_fw_resp_new(void)
  * @region_start:  Start offset of address region in which range of address is looked up.
  * @region_end:  End offset of address region in which range of address is looked up.
  * @width: The width for range of address to be looked up.
- * @error: A [[email protected]]. Error can be generated with two domain of Hinawa.FwNodeError and
- *	   Hinawa.FwRespError.
+ * @error: A [[email protected]]. Error can be generated with two domain of [error@FwNodeError] and
+ *	   [error@FwRespError].
  *
  * Allocate an address range within Linux system for local nodes, each of which expresses 1394
  * OHCI hardware. Once successful, [signal@FwResp::requested] signal will be emitted whenever any
@@ -286,8 +286,8 @@ gboolean hinawa_fw_resp_reserve_within_region(HinawaFwResp *self, HinawaFwNode *
  * @node: A [class@FwNode].
  * @addr: A start address to listen to in 1394 OHCI hardware.
  * @width: The byte width of address to listen to 1394 OHCI hardware.
- * @error: A [[email protected]]. Error can be generated with two domain of Hinawa.FwNodeError and
- *	   and Hinawa.FwRespError.
+ * @error: A [[email protected]]. Error can be generated with two domain of [error@FwNodeError] and
+ *	   and [error@FwRespError].
  *
  * Allocate an address range within Linux system for local nodes, each of which expresses 1394
  * OHCI hardware. Once successful, [signal@FwResp::requested] signal will be emitted whenever any

src/hinawa_enum_types.h

@@ -95,8 +95,8 @@ typedef enum {
  * @HINAWA_FW_REQ_ERROR_NO_ACK:		For no acknowledge.
  * @HINAWA_FW_REQ_ERROR_INVALID:	For rcode out of specification.
  *
- * A set of error code for [[email protected]]. Each of them has the same value as the
- * corresponding enumeration in [enum@Hinawa.FwRcode].
+ * A set of error code for [[email protected]] for operations in [class@FwReq].
+ * The actual value is equivalent to [enum@FwRcode].
  *
  * Since: 2.5.
  */
@@ -122,7 +122,7 @@ typedef enum {
  *					firewire character device.
  * @HINAWA_FW_NODE_ERROR_FAILED:	The system call fails.
  *
- * A set of error code for [[email protected]] with domain which equals to Hinawa.FwNodeError.
+ * A set of error code for [[email protected]] for operations in [class@FwNode].
  *
  * Since: 2.1
  */
@@ -139,7 +139,7 @@ typedef enum {
  * @HINAWA_FW_RESP_ERROR_RESERVED:		The instance is already associated to reserved address range.
  * @HINAWA_FW_RESP_ERROR_ADDR_SPACE_USED:	The address space is used exclusively.
  *
- * A set of error code for [[email protected]] with domain which equals to Hinawa.FwRespError.
+ * A set of error code for [[email protected]] for operations in [class@FwResp].
  *
  * Since: 2.2
  */
@@ -155,7 +155,7 @@ typedef enum {
  * @HINAWA_FW_FCP_ERROR_LARGE_RESP:	The size of response is larger than expected.
  * @HINAWA_FW_FCP_ERROR_ABORTED:	The transaction is aborted due to bus reset.
  *
- * A set of error code for [[email protected]] with domain which equals to Hinawa.FwFcpError.
+ * A set of error code for [[email protected]] for operations in [class@FwFcp].
  *
  * Since: 2.1
  */