From 5e0c402f38ebf36b184edca9b66f1e3abb8e627c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 8 Nov 2023 23:52:42 +0000 Subject: [PATCH] girepository: Update docs for GIUnionInfo for gi-docgen Move the SECTION into the struct docs, update the documentation comment syntax, and add `Since: 2.80` everywhere. Signed-off-by: Philip Withnall Helps: #3155 --- girepository/gitypes.h | 6 +--- girepository/giunioninfo.c | 71 ++++++++++++++++++++++---------------- girepository/giunioninfo.h | 6 ++-- 3 files changed, 47 insertions(+), 36 deletions(-) diff --git a/girepository/gitypes.h b/girepository/gitypes.h index 592110dfd..aa2682586 100644 --- a/girepository/gitypes.h +++ b/girepository/gitypes.h @@ -88,11 +88,7 @@ typedef GIBaseInfo GIRegisteredTypeInfo; */ typedef GIBaseInfo GIStructInfo; -/** - * GIUnionInfo: - * - * Represents a union. - */ +/* Documented in giunioninfo.c */ typedef GIBaseInfo GIUnionInfo; /** diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c index 54b9c0776..7b305c981 100644 --- a/girepository/giunioninfo.c +++ b/girepository/giunioninfo.c @@ -32,15 +32,15 @@ #include "giunioninfo.h" /** - * SECTION:giunioninfo - * @title: GIUnionInfo - * @short_description: Struct representing a union. + * GIUnionInfo: * - * GIUnionInfo represents a union type. + * `GIUnionInfo` represents a union type. * * A union has methods and fields. Unions can optionally have a * discriminator, which is a field deciding what type of real union * fields is valid for specified instance. + * + * Since: 2.80 */ /** @@ -50,6 +50,7 @@ * Obtain the number of fields this union has. * * Returns: number of fields + * Since: 2.80 */ gint gi_union_info_get_n_fields (GIUnionInfo *info) @@ -65,10 +66,11 @@ gi_union_info_get_n_fields (GIUnionInfo *info) * @info: a #GIUnionInfo * @n: a field index * - * Obtain the type information for field with specified index. + * Obtain the type information for the field with the specified index. * - * Returns: (transfer full): the #GIFieldInfo, free it with gi_base_info_unref() - * when done. + * Returns: (transfer full): the [alias@GIRepository.FieldInfo], free it with + * gi_base_info_unref() when done. + * Since: 2.80 */ GIFieldInfo * gi_union_info_get_field (GIUnionInfo *info, @@ -89,6 +91,7 @@ gi_union_info_get_field (GIUnionInfo *info, * Obtain the number of methods this union has. * * Returns: number of methods + * Since: 2.80 */ gint gi_union_info_get_n_methods (GIUnionInfo *info) @@ -104,10 +107,11 @@ gi_union_info_get_n_methods (GIUnionInfo *info) * @info: a #GIUnionInfo * @n: a method index * - * Obtain the type information for method with specified index. + * Obtain the type information for the method with the specified index. * - * Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref() - * when done. + * Returns: (transfer full): the [alias@GIRepository.FunctionInfo], free it + * with gi_base_info_unref() when done. + * Since: 2.80 */ GIFunctionInfo * gi_union_info_get_method (GIUnionInfo *info, @@ -129,9 +133,10 @@ gi_union_info_get_method (GIUnionInfo *info, * gi_union_info_is_discriminated: * @info: a #GIUnionInfo * - * Return true if this union contains discriminator field. + * Return true if this union contains a discriminator field. * - * Returns: %TRUE if this is a discriminated union, %FALSE otherwise + * Returns: true if this is a discriminated union, false otherwise + * Since: 2.80 */ gboolean gi_union_info_is_discriminated (GIUnionInfo *info) @@ -146,9 +151,10 @@ gi_union_info_is_discriminated (GIUnionInfo *info) * gi_union_info_get_discriminator_offset: * @info: a #GIUnionInfo * - * Returns offset of the discriminator field in the structure. + * Returns the offset of the discriminator field in the structure. * - * Returns: offset in bytes of the discriminator + * Returns: offset, in bytes, of the discriminator + * Since: 2.80 */ gint gi_union_info_get_discriminator_offset (GIUnionInfo *info) @@ -165,8 +171,9 @@ gi_union_info_get_discriminator_offset (GIUnionInfo *info) * * Obtain the type information of the union discriminator. * - * Returns: (transfer full): the #GITypeInfo, free it with gi_base_info_unref() - * when done. + * Returns: (transfer full): the [alias@GIRepository.TypeInfo], free it with + * gi_base_info_unref() when done. + * Since: 2.80 */ GITypeInfo * gi_union_info_get_discriminator_type (GIUnionInfo *info) @@ -181,12 +188,15 @@ gi_union_info_get_discriminator_type (GIUnionInfo *info) * @info: a #GIUnionInfo * @n: a union field index * - * Obtain discriminator value assigned for n-th union field, i.e. n-th - * union field is the active one if discriminator contains this + * Obtain the discriminator value assigned for n-th union field, i.e. the n-th + * union field is the active one if the discriminator contains this * constant. * - * Returns: (transfer full): the #GIConstantInfo, free it with gi_base_info_unref() - * when done. + * If the union is not discriminated, `NULL` is returned. + * + * Returns: (transfer full): the [alias@GIRepository.ConstantInfo], free it + * with gi_base_info_unref() when done. + * Since: 2.80 */ GIConstantInfo * gi_union_info_get_discriminator (GIUnionInfo *info, @@ -217,10 +227,11 @@ gi_union_info_get_discriminator (GIUnionInfo *info, * @info: a #GIUnionInfo * @name: a method name * - * Obtain the type information for method named @name. + * Obtain the type information for the method named @name. * - * Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref() - * when done. + * Returns: (transfer full): the [alias@GIRepository.FunctionInfo], free it + * with gi_base_info_unref() when done. + * Since: 2.80 */ GIFunctionInfo * gi_union_info_find_method (GIUnionInfo *info, @@ -243,7 +254,8 @@ gi_union_info_find_method (GIUnionInfo *info, * * Obtain the total size of the union. * - * Returns: size of the union in bytes + * Returns: size of the union, in bytes + * Since: 2.80 */ gsize gi_union_info_get_size (GIUnionInfo *info) @@ -260,7 +272,8 @@ gi_union_info_get_size (GIUnionInfo *info) * * Obtain the required alignment of the union. * - * Returns: required alignment in bytes + * Returns: required alignment, in bytes + * Since: 2.80 */ gsize gi_union_info_get_alignment (GIUnionInfo *info) @@ -277,8 +290,8 @@ gi_union_info_get_alignment (GIUnionInfo *info) * * Retrieves the name of the copy function for @info, if any is set. * - * Returns: (transfer none) (nullable): the name of the copy function - * + * Returns: (transfer none) (nullable): the name of the copy function, or `NULL` + * if none is set * Since: 2.80 */ const char * @@ -304,8 +317,8 @@ gi_union_info_get_copy_function (GIUnionInfo *info) * * Retrieves the name of the free function for @info, if any is set. * - * Returns: (transfer none) (nullable): the name of the free function - * + * Returns: (transfer none) (nullable): the name of the free function, or `NULL` + * if none is set * Since: 2.80 */ const char * diff --git a/girepository/giunioninfo.h b/girepository/giunioninfo.h index d45389b2b..ed941dc0c 100644 --- a/girepository/giunioninfo.h +++ b/girepository/giunioninfo.h @@ -33,10 +33,12 @@ G_BEGIN_DECLS /** - * GI_IS_UNION_INFO + * GI_IS_UNION_INFO: * @info: an info structure * - * Checks if @info is a #GIUnionInfo. + * Checks if @info is a [struct@GIRepository.UnionInfo]. + * + * Since: 2.80 */ #define GI_IS_UNION_INFO(info) \ (gi_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_UNION)