diff options
author | Takashi Sakamoto <o-takashi@sakamocchi.jp> | 2023-10-29 15:33:14 +0900 |
---|---|---|
committer | 坂本 貴史 <o-takashi@sakamocchi.jp> | 2023-10-29 15:39:12 +0900 |
commit | 9daef104d87a2c65e1deee6ba2020f2e2f470bc2 (patch) | |
tree | 9d04b28aabdf16e0e377fdb4f6c0bc4597199cef | |
parent | 41b3ddfb2ff775f3494c93a59d1aedf033f3e3c6 (diff) | |
download | libhinoko-9daef104d87a2c65e1deee6ba2020f2e2f470bc2.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 | 28 | ||||
-rw-r--r-- | README.rst | 2 | ||||
-rw-r--r-- | doc/meson.build | 2 | ||||
-rw-r--r-- | src/fw_iso_ctx.c | 5 | ||||
-rw-r--r-- | src/fw_iso_resource.c | 18 | ||||
-rw-r--r-- | src/fw_iso_resource.h | 8 | ||||
-rw-r--r-- | src/fw_iso_resource_auto.c | 12 | ||||
-rw-r--r-- | src/fw_iso_resource_once.c | 4 | ||||
-rw-r--r-- | src/hinoko_enum_types.h | 6 |
9 files changed, 54 insertions, 31 deletions
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 47da1b5..4301655 100644 --- 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 @@ -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 index 4de409a..a62299b 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_iso_ctx.c b/src/fw_iso_ctx.c index 7aee512..ace0d3a 100644 --- a/src/fw_iso_ctx.c +++ b/src/fw_iso_ctx.c @@ -16,8 +16,7 @@ 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]. */ @@ -25,7 +24,7 @@ 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 index 8977a33..560ef2b 100644 --- a/src/fw_iso_resource.c +++ b/src/fw_iso_resource.c @@ -16,8 +16,8 @@ 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]. */ @@ -25,7 +25,7 @@ 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 index 688709b..25d1638 100644 --- 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 index f6f8a64..4b435ba 100644 --- a/src/fw_iso_resource_auto.c +++ b/src/fw_iso_resource_auto.c @@ -30,7 +30,7 @@ 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]. */ @@ -38,7 +38,7 @@ G_DEFINE_QUARK(hinoko-fw-iso-resource-auto-error-quark, hinoko_fw_iso_resource_a /** * 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 @@ end: * 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 index 38d8e17..b8d025f 100644 --- 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 index 7714538..b56c79d 100644 --- 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, |