From 7f2091a5cabb875a72949de2073b1f63c79b426b Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 13 Dec 2023 00:27:07 +0000 Subject: [PATCH] gienuminfo: Port documentation to gi-docgen and update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Helps: #3155 --- girepository/gienuminfo.c | 47 ++++++++++++++++++++++++++------------- girepository/gienuminfo.h | 12 ++++++---- 2 files changed, 39 insertions(+), 20 deletions(-) diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c index 09fdf3aa2..24e4a4cde 100644 --- a/girepository/gienuminfo.c +++ b/girepository/gienuminfo.c @@ -33,17 +33,17 @@ #include "gienuminfo.h" /** - * SECTION:gienuminfo - * @title: GIEnumInfo - * @short_description: Structs representing an enumeration and its values + * GIEnumInfo: * - * A GIEnumInfo represents an enumeration, and a GIValueInfo represents - * a value in the enumeration. + * A `GIEnumInfo` represents an 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 - * a GIEnumInfo. + * The [class@GIRepository.ValueInfo] for a value is fetched by calling + * [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 - * with this enum, or %NULL. + * Returns: (transfer none) (nullable): the string form of the error domain + * 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, - * free the struct with gi_base_info_unref() when done. + * Returns: (transfer full): the enumeration value, free the struct with + * [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 - * gi_base_info_unref() when done. + * Returns: (transfer full): the [class@GIRepository.FunctionInfo]. Free the + * 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) diff --git a/girepository/gienuminfo.h b/girepository/gienuminfo.h index d0a095ea9..c1427b566 100644 --- a/girepository/gienuminfo.h +++ b/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)