diff options
author | Takashi Sakamoto <o-takashi@sakamocchi.jp> | 2023-10-29 13:23:20 +0900 |
---|---|---|
committer | 坂本 貴史 <o-takashi@sakamocchi.jp> | 2023-10-29 13:27:39 +0900 |
commit | 3c3d9b6f459b9262edabc836fba272633f5894d4 (patch) | |
tree | 37b03a2fdee28c0fcda0ee8d350975bd293f39f8 | |
parent | ed8fdc163b30b97ffd3d38b7f2f2a0f66030707f (diff) | |
download | libhinawa-3c3d9b6f459b9262edabc836fba272633f5894d4.tar.gz |
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>
-rw-r--r-- | .github/workflows/build.yml | 34 | ||||
-rw-r--r-- | README.rst | 2 | ||||
-rw-r--r-- | doc/meson.build | 2 | ||||
-rw-r--r-- | src/fw_fcp.c | 20 | ||||
-rw-r--r-- | src/fw_node.c | 8 | ||||
-rw-r--r-- | src/fw_req.c | 12 | ||||
-rw-r--r-- | src/fw_resp.c | 10 | ||||
-rw-r--r-- | src/hinawa_enum_types.h | 10 |
8 files changed, 62 insertions, 36 deletions
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 08c56d2..db3a6ef 100644 --- a/.github/workflows/build.yml +++ b/.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,8 +54,6 @@ jobs: container: image: ubuntu:latest steps: - - name: Checkout repository. - uses: actions/checkout@v3 - name: Prepare build environment. run: | DEBIAN_FRONTEND=noninteractive apt-get update @@ -50,6 +61,21 @@ jobs: 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 @@ -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 ============ diff --git a/doc/meson.build b/doc/meson.build index a71fb16..51ffa86 100644 --- 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_fcp.c b/src/fw_fcp.c index 967fb74..692810b 100644 --- a/src/fw_fcp.c +++ b/src/fw_fcp.c @@ -23,7 +23,7 @@ /** * hinawa_fw_fcp_error_quark: * - * Return the [alias@GLib.Quark] for [struct@GLib.Error] which has code in Hinawa.FwFcpError. + * Return the [alias@GLib.Quark] for [struct@GLib.Error] 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 [struct@GLib.Error]. Error can be generated with four domains; Hinoko.FwNodeError and - * Hinoko.FwReqError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with four domains; Hinoko.FwNodeError and - * Hinoko.FwReqError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with four domains; Hinawa.FwNodeError, - * Hinawa.FwReqError, and Hinawa.FwFcpError. + * @error: A [struct@GLib.Error]. 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 @@ end: * @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 [struct@GLib.Error]. Error can be generated with four domains; Hinawa.FwNodeError, - * Hinawa.FwReqError, and Hinawa.FwFcpError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with domain of Hinawa.FwFcpError. + * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwFcpError]. * * Start to listen to FCP responses. * diff --git a/src/fw_node.c b/src/fw_node.c index f7de24a..da730e9 100644 --- a/src/fw_node.c +++ b/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 [alias@GLib.Quark] for [struct@GLib.Error] with Hinawa.FwNodeError domain. + * Return the [alias@GLib.Quark] for [struct@GLib.Error] 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 [struct@GLib.Error]. Error can be generated with two domains; GLib.Error and - * Hinawa.FwNodeError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Source]. - * @error: A [struct@GLib.Error]. Error can be generated with domain of Hinawa.FwNodeError. + * @error: A [struct@GLib.Error]. Error can be generated with domain of [error@FwNodeError]. * * Create [struct@GLib.Source] for [struct@GLib.MainContext] to dispatch events for the node on * IEEE 1394 bus. diff --git a/src/fw_req.c b/src/fw_req.c index a8ccc2a..2085079 100644 --- a/src/fw_req.c +++ b/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 [struct@GLib.Error]. Error can be generated with two domains; Hinawa.FwNodeError and - * Hinawa.FwReqError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with two domains; Hinawa.FwNodeError and - * Hinawa.FwReqError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with two domains; Hinawa.FwNodeError and - * Hinawa.FwReqError. + * @error: A [struct@GLib.Error]. 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 diff --git a/src/fw_resp.c b/src/fw_resp.c index 728663d..bd08fa3 100644 --- a/src/fw_resp.c +++ b/src/fw_resp.c @@ -16,7 +16,7 @@ * hinawa_fw_resp_error_quark: * * Return the [alias@GLib.Quark] for error domain of [struct@GLib.Error] 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 [struct@GLib.Error]. Error can be generated with two domain of Hinawa.FwNodeError and - * Hinawa.FwRespError. + * @error: A [struct@GLib.Error]. 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 [struct@GLib.Error]. Error can be generated with two domain of Hinawa.FwNodeError and - * and Hinawa.FwRespError. + * @error: A [struct@GLib.Error]. 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 diff --git a/src/hinawa_enum_types.h b/src/hinawa_enum_types.h index 9f2dea1..1687046 100644 --- a/src/hinawa_enum_types.h +++ b/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 [class@Hinawa.FwReq]. Each of them has the same value as the - * corresponding enumeration in [enum@Hinawa.FwRcode]. + * A set of error code for [struct@GLib.Error] 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 [struct@GLib.Error] with domain which equals to Hinawa.FwNodeError. + * A set of error code for [struct@GLib.Error] 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 [struct@GLib.Error] with domain which equals to Hinawa.FwRespError. + * A set of error code for [struct@GLib.Error] 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 [struct@GLib.Error] with domain which equals to Hinawa.FwFcpError. + * A set of error code for [struct@GLib.Error] for operations in [class@FwFcp]. * * Since: 2.1 */ |