gienuminfo: 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/gienuminfo.c

@@ -33,17 +33,17 @@
 #include "gienuminfo.h"
 
 /**
- * SECTION:gienuminfo
+ * GIEnumInfo:
- * @title: GIEnumInfo
- * @short_description: Structs representing an enumeration and its values
  *
- * A GIEnumInfo represents an enumeration, and a GIValueInfo represents
+ * A `GIEnumInfo` represents an enumeration.
- * a value in the enumeration.
  *
- * The GIEnumInfo contains a set of values and a type.
+ * The `GIEnumInfo` contains a set of values (each a
+ * [class@GIRepository.ValueInfo]) and a type.
  *
- * The GIValueInfo is fetched by calling gi_enum_info_get_value() on
+ * The [class@GIRepository.ValueInfo] for a value is fetched by calling
- * a GIEnumInfo.
+ * [method@GIRepository.EnumInfo.get_value] on a `GIEnumInfo`.
+ *
+ * Since: 2.80
  */
 
 /**
@@ -53,6 +53,7 @@
  * Obtain the number of values this enumeration contains.
  *
  * Returns: the number of enumeration values
+ * Since: 2.80
  */
 guint
 gi_enum_info_get_n_values (GIEnumInfo *info)
@@ -75,8 +76,8 @@ gi_enum_info_get_n_values (GIEnumInfo *info)
  * Obtain the string form of the quark for the error domain associated with
  * this enum, if any.
  *
- * Returns: (transfer none): the string form of the error domain associated
+ * Returns: (transfer none) (nullable): the string form of the error domain
- * with this enum, or %NULL.
+ *   associated with this enum, or `NULL`.
  * Since: 2.80
  */
 const gchar *
@@ -103,8 +104,9 @@ gi_enum_info_get_error_domain (GIEnumInfo *info)
  *
  * Obtain a value for this enumeration.
  *
- * Returns: (transfer full): the enumeration value or %NULL if type tag is wrong,
+ * Returns: (transfer full): the enumeration value, free the struct with
- *   free the struct with gi_base_info_unref() when done.
+ *   [method@GIRepository.BaseInfo.unref] when done.
+ * Since: 2.80
  */
 GIValueInfo *
 gi_enum_info_get_value (GIEnumInfo *info,
@@ -154,8 +156,8 @@ gi_enum_info_get_n_methods (GIEnumInfo *info)
  *
  * Obtain an enum type method at index @n.
  *
- * Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
+ * Returns: (transfer full): the [class@GIRepository.FunctionInfo]. Free the
- *   gi_base_info_unref() when done.
+ *   struct by calling [method@GIRepository.BaseInfo.unref] when done.
  * Since: 2.80
  */
 GIFunctionInfo *
@@ -193,6 +195,7 @@ gi_enum_info_get_method (GIEnumInfo *info,
  * may not match the sign of the type used by the C compiler.
  *
  * Returns: the storage type for the enumeration
+ * Since: 2.80
  */
 GITypeTag
 gi_enum_info_get_storage_type (GIEnumInfo *info)
@@ -217,15 +220,27 @@ gi_enum_info_class_init (gpointer g_class,
   info_class->info_type = GI_INFO_TYPE_ENUM;
 }
 
+/**
+ * GIValueInfo:
+ *
+ * A `GIValueInfo` represents a value in an enumeration.
+ *
+ * The `GIValueInfo` is fetched by calling
+ * [method@GIRepository.EnumInfo.get_value] on a [class@GIRepository.EnumInfo].
+ *
+ * Since: 2.80
+ */
+
 /**
  * gi_value_info_get_value:
  * @info: a #GIValueInfo
  *
- * Obtain the enumeration value of the #GIValueInfo.
+ * Obtain the enumeration value of the `GIValueInfo`.
  *
  * Returns: the enumeration value. This will always be representable
- *   as a 32-bit signed or unsigned value. The use of gint64 as the
+ *   as a 32-bit signed or unsigned value. The use of `gint64` as the
  *   return type is to allow both.
+ * Since: 2.80
  */
 gint64
 gi_value_info_get_value (GIValueInfo *info)

girepository/gienuminfo.h

@@ -33,20 +33,24 @@
 G_BEGIN_DECLS
 
 /**
- * GI_IS_ENUM_INFO
+ * GI_IS_ENUM_INFO:
  * @info: an info structure
  *
- * Checks if @info is a #GIEnumInfo.
+ * Checks if @info is a [class@GIRepository.EnumInfo].
+ *
+ * Since: 2.80
  */
 #define GI_IS_ENUM_INFO(info) \
     ((gi_base_info_get_info_type ((GIBaseInfo*) info) ==  GI_INFO_TYPE_ENUM) || \
      (gi_base_info_get_info_type ((GIBaseInfo*) info) ==  GI_INFO_TYPE_FLAGS))
 
 /**
- * GI_IS_VALUE_INFO
+ * GI_IS_VALUE_INFO:
  * @info: an info structure
  *
- * Checks if @info is a #GIValueInfo.
+ * Checks if @info is a [class@GIRepository.ValueInfo].
+ *
+ * Since: 2.80
  */
 #define GI_IS_VALUE_INFO(info) \
     (gi_base_info_get_info_type ((GIBaseInfo*) info) ==  GI_INFO_TYPE_VALUE)