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 <pwithnall@gnome.org>

Helps: #3155

girepository/gitypes.h

@@ -88,11 +88,7 @@ typedef GIBaseInfo GIRegisteredTypeInfo;
  */
 typedef GIBaseInfo GIStructInfo;
 
-/**
+/* Documented in giunioninfo.c */
- * GIUnionInfo:
- *
- * Represents a union.
- */
 typedef GIBaseInfo GIUnionInfo;
 
 /**

girepository/giunioninfo.c

@@ -32,15 +32,15 @@
 #include "giunioninfo.h"
 
 /**
- * SECTION:giunioninfo
+ * GIUnionInfo:
- * @title: GIUnionInfo
- * @short_description: Struct representing a union.
  *
- * 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()
+ * Returns: (transfer full): the [alias@GIRepository.FieldInfo], free it with
- * when done.
+ *   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()
+ * Returns: (transfer full): the [alias@GIRepository.FunctionInfo], free it
- * when done.
+ *   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()
+ * Returns: (transfer full): the [alias@GIRepository.TypeInfo], free it with
- * when done.
+ *   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
+ * Obtain the discriminator value assigned for n-th union field, i.e. the n-th
- * union field is the active one if discriminator contains this
+ * union field is the active one if the discriminator contains this
  * constant.
  *
- * Returns: (transfer full): the #GIConstantInfo, free it with gi_base_info_unref()
+ * If the union is not discriminated, `NULL` is returned.
- * when done.
+ *
+ * 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()
+ * Returns: (transfer full): the [alias@GIRepository.FunctionInfo], free it
- * when done.
+ *   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 *

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)