gistructinfo: Port documentation to gi-docgen and update

Review and update the documentation, making sure it’s complete,
formatted in gi-docgen format, and has all appropriate GIR annotations
and `Since:` lines.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3155

girepository/gistructinfo.c

@@ -35,13 +35,13 @@
 #include "gistructinfo.h"
 
 /**
- * SECTION:gistructinfo
+ * GIStructInfo:
- * @title: GIStructInfo
- * @short_description: Struct representing a C structure
  *
- * GIStructInfo represents a generic C structure type.
+ * `GIStructInfo` represents a generic C structure type.
  *
  * A structure has methods and fields.
+ *
+ * Since: 2.80
  */
 
 /**
@@ -51,6 +51,7 @@
  * Obtain the number of fields this structure has.
  *
  * Returns: number of fields
+ * Since: 2.80
  */
 guint
 gi_struct_info_get_n_fields (GIStructInfo *info)
@@ -68,7 +69,8 @@ gi_struct_info_get_n_fields (GIStructInfo *info)
  *
  * Obtain the offset of the specified field.
  *
- * Returns: field offset in bytes
+ * Returns: field offset, in bytes
+ * Since: 2.80
  */
 static gint32
 gi_struct_get_field_offset (GIStructInfo *info,
@@ -97,8 +99,9 @@ gi_struct_get_field_offset (GIStructInfo *info,
  *
  * Obtain the type information for field with specified index.
  *
- * Returns: (transfer full): the #GIFieldInfo, free it with gi_base_info_unref()
+ * Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free it with
- * when done.
+ *   [method@GIRepository.BaseInfo.unref] when done.
+ * Since: 2.80
  */
 GIFieldInfo *
 gi_struct_info_get_field (GIStructInfo *info,
@@ -117,9 +120,10 @@ gi_struct_info_get_field (GIStructInfo *info,
  *
  * Obtain the type information for field named @name.
  *
+ * Returns: (transfer full) (nullable): The [class@GIRepository.FieldInfo], or
+ *   `NULL` if not found. Free it with [method@GIRepository.BaseInfo.unref] when
+ *   done.
  * Since: 2.80
- * Returns: (transfer full): the #GIFieldInfo or %NULL if not found,
- * free it with gi_base_info_unref() when done.
  */
 GIFieldInfo *
 gi_struct_info_find_field (GIStructInfo *info,
@@ -159,6 +163,7 @@ gi_struct_info_find_field (GIStructInfo *info,
  * Obtain the number of methods this structure has.
  *
  * Returns: number of methods
+ * Since: 2.80
  */
 guint
 gi_struct_info_get_n_methods (GIStructInfo *info)
@@ -176,8 +181,9 @@ gi_struct_info_get_n_methods (GIStructInfo *info)
  *
  * Obtain the type information for method with specified index.
  *
- * Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
+ * Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free it with
- * when done.
+ *   [method@GIRepository.BaseInfo.unref] when done.
+ * Since: 2.80
  */
 GIFunctionInfo *
 gi_struct_info_get_method (GIStructInfo *info,
@@ -200,8 +206,10 @@ gi_struct_info_get_method (GIStructInfo *info,
  *
  * Obtain the type information for method named @name.
  *
- * Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
+ * Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
- * when done.
+ *   or `NULL` if none was found. Free it with
+ *   [method@GIRepository.BaseInfo.unref] when done.
+ * Since: 2.80
  */
 GIFunctionInfo *
 gi_struct_info_find_method (GIStructInfo *info,
@@ -221,7 +229,8 @@ gi_struct_info_find_method (GIStructInfo *info,
  *
  * Obtain the total size of the structure.
  *
- * Returns: size of the structure in bytes
+ * Returns: size of the structure, in bytes
+ * Since: 2.80
  */
 gsize
 gi_struct_info_get_size (GIStructInfo *info)
@@ -238,7 +247,8 @@ gi_struct_info_get_size (GIStructInfo *info)
  *
  * Obtain the required alignment of the structure.
  *
- * Returns: required alignment in bytes
+ * Returns: required alignment, in bytes
+ * Since: 2.80
  */
 gsize
 gi_struct_info_get_alignment (GIStructInfo *info)
@@ -251,11 +261,13 @@ gi_struct_info_get_alignment (GIStructInfo *info)
 
 /**
  * gi_struct_info_is_foreign:
- * @info: TODO
+ * @info: a #GIStructInfo
  *
- * TODO
+ * Gets whether the structure is foreign, i.e. if it’s expected to be overridden
+ * by a native language binding instead of relying of introspected bindings.
  *
- * Returns: TODO
+ * Returns: `TRUE` if the structure is foreign
+ * Since: 2.80
  */
 gboolean
 gi_struct_info_is_foreign (GIStructInfo *info)
@@ -270,11 +282,14 @@ gi_struct_info_is_foreign (GIStructInfo *info)
  * gi_struct_info_is_gtype_struct:
  * @info: a #GIStructInfo
  *
- * Return true if this structure represents the "class structure" for some
+ * Return true if this structure represents the ‘class structure’ for some
- * #GObject or #GInterface.  This function is mainly useful to hide this kind of structure
+ * [class@GObject.Object] or `GInterface`.
- * from generated public APIs.
  *
- * Returns: %TRUE if this is a class struct, %FALSE otherwise
+ * This function is mainly useful to hide this kind of structure from generated
+ * public APIs.
+ *
+ * Returns: `TRUE` if this is a class struct, `FALSE` otherwise
+ * Since: 2.80
  */
 gboolean
 gi_struct_info_is_gtype_struct (GIStructInfo *info)
@@ -291,8 +306,8 @@ gi_struct_info_is_gtype_struct (GIStructInfo *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 the structure has no copy function
  * Since: 2.80
  */
 const char *
@@ -318,8 +333,8 @@ gi_struct_info_get_copy_function_name (GIStructInfo *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 the structure has no free function
  * Since: 2.80
  */
 const char *

girepository/gistructinfo.h

@@ -33,10 +33,12 @@
 G_BEGIN_DECLS
 
 /**
- * GI_IS_STRUCT_INFO
+ * GI_IS_STRUCT_INFO:
  * @info: an info structure
  *
- * Checks if @info is a #GIStructInfo.
+ * Checks if @info is a [class@GIRepository.StructInfo].
+ *
+ * Since: 2.80
  */
 #define GI_IS_STRUCT_INFO(info) \
     (gi_base_info_get_info_type ((GIBaseInfo*) info) ==  GI_INFO_TYPE_STRUCT)