From fecf2b2e7bcf49116d50f0b78d59169f3849f0ba Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 1 Oct 2024 19:54:40 +0100 Subject: [PATCH 1/2] gvarianttype: Add two missing (nullable) annotations Spotted while working on the docs (see the following commit). Signed-off-by: Philip Withnall --- glib/gvarianttype.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c index 9b2fc7051..2bf9aa1dc 100644 --- a/glib/gvarianttype.c +++ b/glib/gvarianttype.c @@ -950,8 +950,8 @@ g_variant_type_element (const GVariantType *type) * This call, together with g_variant_type_next() provides an iterator * interface over tuple and dictionary entry types. * - * Returns: (transfer none): the first item type of @type, or %NULL - * + * Returns: (transfer none) (nullable): the first item type of @type, or %NULL + * if the type has no item types * Since 2.24 **/ const GVariantType * @@ -986,7 +986,8 @@ g_variant_type_first (const GVariantType *type) * * For tuples, %NULL is returned when @type is the last item in a tuple. * - * Returns: (transfer none): the next #GVariantType after @type, or %NULL + * Returns: (transfer none) (nullable): the next type after @type, or %NULL if + * there are no further types * * Since 2.24 **/ From c6340430db2dc0ed583e0a614a813b9ac0b3f6e6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 1 Oct 2024 19:55:28 +0100 Subject: [PATCH 2/2] gvarianttype: Convert docs to gi-docgen linking syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit And improve formatting in a few places while I’m there: * Add quotes around ‘maybe’ types to make it clearer that ‘maybe’ is being used as a proper noun * Add linebreaks so that all doc comments start with a single-sentence summary of the method * Improve formatting of constants * Add a few links to external specifications See https://developer.gnome.org/documentation/guidelines/devel-docs.html Signed-off-by: Philip Withnall Helps: #3250 --- glib/gvarianttype.c | 306 +++++++++++++++++++++----------------------- glib/gvarianttype.h | 74 ++++++----- 2 files changed, 191 insertions(+), 189 deletions(-) diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c index 2bf9aa1dc..d92b966f7 100644 --- a/glib/gvarianttype.c +++ b/glib/gvarianttype.c @@ -276,10 +276,11 @@ variant_type_string_scan_internal (const gchar *string, /** * g_variant_type_string_scan: * @string: a pointer to any string - * @limit: (nullable): the end of @string, or %NULL - * @endptr: (out) (optional): location to store the end pointer, or %NULL + * @limit: (nullable): the end of @string + * @endptr: (out) (optional): location to store the end pointer * * Scan for a single complete and valid GVariant type string in @string. + * * The memory pointed to by @limit (or bytes beyond it) is never * accessed. * @@ -291,10 +292,9 @@ variant_type_string_scan_internal (const gchar *string, * string does not end before @limit then %FALSE is returned. * * For the simple case of checking if a string is a valid type string, - * see g_variant_type_string_is_valid(). - * - * Returns: %TRUE if a valid type string was found + * see [func@GLib.VariantType.string_is_valid]. * + * Returns: true if a valid type string was found * Since: 2.24 **/ gboolean @@ -314,9 +314,9 @@ g_variant_type_string_scan (const gchar *string, * return depth 1, and a container type will return a greater value. The depth * of a tuple is 1 plus the depth of its deepest child type. * - * If @type_string is not a valid #GVariant type string, 0 will be returned. + * If @type_string is not a valid [type@GLib.Variant] type string, `0` will be returned. * - * Returns: depth of @type_string, or 0 on error + * Returns: depth of @type_string, or `0` on error * Since: 2.60 */ gsize @@ -339,12 +339,13 @@ g_variant_type_string_get_depth_ (const gchar *type_string) * g_variant_type_string_is_valid: * @type_string: a pointer to any string * - * Checks if @type_string is a valid GVariant type string. This call is - * equivalent to calling g_variant_type_string_scan() and confirming - * that the following character is a nul terminator. + * Checks if @type_string is a valid + * [GVariant type string](./struct.VariantType.html#gvariant-type-strings). * - * Returns: %TRUE if @type_string is exactly one valid type string + * This call is equivalent to calling [func@GLib.VariantType.string_scan] and + * confirming that the following character is a nul terminator. * + * Returns: true if @type_string is exactly one valid type string * Since 2.24 **/ gboolean @@ -362,13 +363,13 @@ g_variant_type_string_is_valid (const gchar *type_string) /** * g_variant_type_free: - * @type: (nullable): a #GVariantType, or %NULL + * @type: (nullable): type to free * - * Frees a #GVariantType that was allocated with - * g_variant_type_copy(), g_variant_type_new() or one of the container - * type constructor functions. + * Frees a [type@GLib.VariantType] that was allocated with + * [method@GLib.VariantType.copy], [ctor@GLib.VariantType.new] or one of the + * container type constructor functions. * - * In the case that @type is %NULL, this function does nothing. + * In the case that @type is `NULL`, this function does nothing. * * Since 2.24 **/ @@ -382,13 +383,14 @@ g_variant_type_free (GVariantType *type) /** * g_variant_type_copy: - * @type: a #GVariantType + * @type: (not nullable): type to copy * - * Makes a copy of a #GVariantType. It is appropriate to call - * g_variant_type_free() on the return value. @type may not be %NULL. + * Makes a copy of a [type@GLib.VariantType]. * - * Returns: (transfer full): a new #GVariantType + * It is appropriate to call [method@GLib.VariantType.free] on the return value. + * @type may not be `NULL`. * + * Returns: (transfer full): a new [type@GLib.VariantType] * Since 2.24 **/ GVariantType * @@ -410,17 +412,17 @@ g_variant_type_copy (const GVariantType *type) /** * g_variant_type_new: - * @type_string: a valid GVariant type string + * @type_string: a valid [GVariant type string](./struct.VariantType.html#gvariant-type-strings) * - * Creates a new #GVariantType corresponding to the type string given - * by @type_string. It is appropriate to call g_variant_type_free() on - * the return value. + * Creates a new [type@GLib.VariantType] corresponding to the type string given + * by @type_string. + * + * It is appropriate to call [method@GLib.VariantType.free] on the return value. * * It is a programmer error to call this function with an invalid type - * string. Use g_variant_type_string_is_valid() if you are unsure. - * - * Returns: (transfer full): a new #GVariantType + * string. Use [func@GLib.VariantType.string_is_valid] if you are unsure. * + * Returns: (transfer full): a new [type@GLib.VariantType] * Since: 2.24 */ GVariantType * @@ -433,14 +435,14 @@ g_variant_type_new (const gchar *type_string) /** * g_variant_type_get_string_length: - * @type: a #GVariantType + * @type: type to measure * - * Returns the length of the type string corresponding to the given - * @type. This function must be used to determine the valid extent of - * the memory region returned by g_variant_type_peek_string(). + * Returns the length of the type string corresponding to the given @type. + * + * This function must be used to determine the valid extent of + * the memory region returned by [method@GLib.VariantType.peek_string]. * * Returns: the length of the corresponding type string - * * Since 2.24 **/ gsize @@ -476,16 +478,16 @@ g_variant_type_get_string_length (const GVariantType *type) */ /** * g_variant_type_peek_string: (skip) - * @type: a #GVariantType + * @type: type to peek at * - * Returns the type string corresponding to the given @type. The - * result is not nul-terminated; in order to determine its length you - * must call g_variant_type_get_string_length(). + * Returns the type string corresponding to the given @type. * - * To get a nul-terminated string, see g_variant_type_dup_string(). + * The result is not nul-terminated; in order to determine its length you + * must call [method@GLib.VariantType.get_string_length]. + * + * To get a nul-terminated string, see [method@GLib.VariantType.dup_string]. * * Returns: the corresponding type string (not nul-terminated) - * * Since 2.24 **/ const gchar * @@ -498,14 +500,14 @@ g_variant_type_peek_string (const GVariantType *type) /** * g_variant_type_dup_string: - * @type: a #GVariantType + * @type: type to copy * - * Returns a newly-allocated copy of the type string corresponding to - * @type. The returned string is nul-terminated. It is appropriate to - * call g_free() on the return value. + * Returns a newly-allocated copy of the type string corresponding to @type. + * + * The returned string is nul-terminated. It is appropriate to call + * [func@GLib.free] on the return value. * * Returns: (transfer full): the corresponding type string - * * Since 2.24 **/ gchar * @@ -519,21 +521,20 @@ g_variant_type_dup_string (const GVariantType *type) /** * g_variant_type_is_definite: - * @type: a #GVariantType + * @type: type to check * * Determines if the given @type is definite (ie: not indefinite). * * A type is definite if its type string does not contain any indefinite - * type characters ('*', '?', or 'r'). + * type characters (`*`, `?`, or `r`). * - * A #GVariant instance may not have an indefinite type, so calling - * this function on the result of g_variant_get_type() will always - * result in %TRUE being returned. Calling this function on an - * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in - * %FALSE being returned. - * - * Returns: %TRUE if @type is definite + * A [type@GLib.Variant] instance may not have an indefinite type, so calling + * this function on the result of [method@GLib.Variant.get_type] will always + * result in true being returned. Calling this function on an + * indefinite type like `G_VARIANT_TYPE_ARRAY`, however, will result in + * `FALSE` being returned. * + * Returns: true if @type is definite * Since 2.24 **/ gboolean @@ -559,19 +560,18 @@ g_variant_type_is_definite (const GVariantType *type) /** * g_variant_type_is_container: - * @type: a #GVariantType + * @type: type to check * * Determines if the given @type is a container type. * * Container types are any array, maybe, tuple, or dictionary * entry types plus the variant type. * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for + * This function returns true for any indefinite type for which every + * definite subtype is a container — `G_VARIANT_TYPE_ARRAY`, for * example. * - * Returns: %TRUE if @type is a container type - * + * Returns: true if @type is a container type * Since 2.24 **/ gboolean @@ -599,7 +599,7 @@ g_variant_type_is_container (const GVariantType *type) /** * g_variant_type_is_basic: - * @type: a #GVariantType + * @type: type to check * * Determines if the given @type is a basic type. * @@ -608,11 +608,10 @@ g_variant_type_is_container (const GVariantType *type) * * Only a basic type may be used as the key of a dictionary entry. * - * This function returns %FALSE for all indefinite types except - * %G_VARIANT_TYPE_BASIC. - * - * Returns: %TRUE if @type is a basic type + * This function returns `FALSE` for all indefinite types except + * `G_VARIANT_TYPE_BASIC`. * + * Returns: true if @type is a basic type * Since 2.24 **/ gboolean @@ -648,17 +647,17 @@ g_variant_type_is_basic (const GVariantType *type) /** * g_variant_type_is_maybe: - * @type: a #GVariantType + * @type: type to check * - * Determines if the given @type is a maybe type. This is true if the - * type string for @type starts with an 'm'. + * Determines if the given @type is a ‘maybe’ type. * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for + * This is true if the type string for @type starts with an `m`. + * + * This function returns true for any indefinite type for which every + * definite subtype is a ‘maybe’ type — `G_VARIANT_TYPE_MAYBE`, for * example. * - * Returns: %TRUE if @type is a maybe type - * + * Returns: true if @type is a ‘maybe’ type * Since 2.24 **/ gboolean @@ -671,17 +670,17 @@ g_variant_type_is_maybe (const GVariantType *type) /** * g_variant_type_is_array: - * @type: a #GVariantType + * @type: type to check * - * Determines if the given @type is an array type. This is true if the - * type string for @type starts with an 'a'. + * Determines if the given @type is an array type. * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for + * This is true if the type string for @type starts with an `a`. + * + * This function returns true for any indefinite type for which every + * definite subtype is an array type — `G_VARIANT_TYPE_ARRAY`, for * example. * - * Returns: %TRUE if @type is an array type - * + * Returns: true if @type is an array type * Since 2.24 **/ gboolean @@ -694,18 +693,18 @@ g_variant_type_is_array (const GVariantType *type) /** * g_variant_type_is_tuple: - * @type: a #GVariantType + * @type: type to check * - * Determines if the given @type is a tuple type. This is true if the - * type string for @type starts with a '(' or if @type is - * %G_VARIANT_TYPE_TUPLE. + * Determines if the given @type is a tuple type. * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for + * This is true if the type string for @type starts with a `(` or if @type is + * `G_VARIANT_TYPE_TUPLE`. + * + * This function returns true for any indefinite type for which every + * definite subtype is a tuple type — `G_VARIANT_TYPE_TUPLE`, for * example. * - * Returns: %TRUE if @type is a tuple type - * + * Returns: true if @type is a tuple type * Since 2.24 **/ gboolean @@ -721,17 +720,17 @@ g_variant_type_is_tuple (const GVariantType *type) /** * g_variant_type_is_dict_entry: - * @type: a #GVariantType + * @type: type to check * - * Determines if the given @type is a dictionary entry type. This is - * true if the type string for @type starts with a '{'. + * Determines if the given @type is a dictionary entry type. * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a dictionary entry type -- - * %G_VARIANT_TYPE_DICT_ENTRY, for example. + * This is true if the type string for @type starts with a `{`. * - * Returns: %TRUE if @type is a dictionary entry type + * This function returns true for any indefinite type for which every + * definite subtype is a dictionary entry type — + * `G_VARIANT_TYPE_DICT_ENTRY`, for example. * + * Returns: true if @type is a dictionary entry type * Since 2.24 **/ gboolean @@ -744,12 +743,11 @@ g_variant_type_is_dict_entry (const GVariantType *type) /** * g_variant_type_is_variant: - * @type: a #GVariantType + * @type: type to check * * Determines if the given @type is the variant type. * - * Returns: %TRUE if @type is the variant type - * + * Returns: true if @type is the variant type * Since 2.24 **/ gboolean @@ -762,16 +760,15 @@ g_variant_type_is_variant (const GVariantType *type) /** * g_variant_type_hash: - * @type: (type GVariantType): a #GVariantType + * @type: (type GVariantType): type to hash * * Hashes @type. * - * The argument type of @type is only #gconstpointer to allow use with - * #GHashTable without function pointer casting. A valid - * #GVariantType must be provided. + * The argument type of @type is only `gconstpointer` to allow use with + * [type@GLib.HashTable] without function pointer casting. A valid + * [type@GLib.VariantType] must be provided. * * Returns: the hash value - * * Since 2.24 **/ guint @@ -784,22 +781,21 @@ g_variant_type_hash (gconstpointer type) /** * g_variant_type_equal: - * @type1: (type GVariantType): a #GVariantType - * @type2: (type GVariantType): a #GVariantType + * @type1: (type GVariantType): type to compare + * @type2: (type GVariantType): another type to compare * * Compares @type1 and @type2 for equality. * - * Only returns %TRUE if the types are exactly equal. Even if one type - * is an indefinite type and the other is a subtype of it, %FALSE will + * Only returns true if the types are exactly equal. Even if one type + * is an indefinite type and the other is a subtype of it, false will * be returned if they are not exactly equal. If you want to check for - * subtypes, use g_variant_type_is_subtype_of(). + * subtypes, use [method@GLib.VariantType.is_subtype_of]. * - * The argument types of @type1 and @type2 are only #gconstpointer to - * allow use with #GHashTable without function pointer casting. For - * both arguments, a valid #GVariantType must be provided. - * - * Returns: %TRUE if @type1 and @type2 are exactly equal + * The argument types of @type1 and @type2 are only `gconstpointer` to + * allow use with [type@GLib.HashTable] without function pointer casting. For + * both arguments, a valid [type@GLib.VariantType] must be provided. * + * Returns: true if @type1 and @type2 are exactly equal * Since 2.24 **/ gboolean @@ -814,17 +810,16 @@ g_variant_type_equal (gconstpointer type1, /** * g_variant_type_is_subtype_of: - * @type: a #GVariantType - * @supertype: a #GVariantType + * @type: type to check + * @supertype: type of potential supertype * * Checks if @type is a subtype of @supertype. * - * This function returns %TRUE if @type is a subtype of @supertype. All + * This function returns true if @type is a subtype of @supertype. All * types are considered to be subtypes of themselves. Aside from that, * only indefinite types can have subtypes. * - * Returns: %TRUE if @type is a subtype of @supertype - * + * Returns: true if @type is a subtype of @supertype * Since 2.24 **/ gboolean @@ -907,14 +902,13 @@ g_variant_type_is_subtype_of (const GVariantType *type, /** * g_variant_type_element: - * @type: an array or maybe #GVariantType + * @type: an array or ‘maybe’ type * - * Determines the element type of an array or maybe type. + * Determines the element type of an array or ‘maybe’ type. * - * This function may only be used with array or maybe types. + * This function may only be used with array or ‘maybe’ types. * * Returns: (transfer none): the element type of @type - * * Since 2.24 **/ const GVariantType * @@ -933,24 +927,24 @@ g_variant_type_element (const GVariantType *type) /** * g_variant_type_first: - * @type: a tuple or dictionary entry #GVariantType + * @type: a tuple or dictionary entry type * * Determines the first item type of a tuple or dictionary entry * type. * * This function may only be used with tuple or dictionary entry types, * but must not be used with the generic tuple type - * %G_VARIANT_TYPE_TUPLE. + * `G_VARIANT_TYPE_TUPLE`. * * In the case of a dictionary entry type, this returns the type of * the key. * - * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. + * `NULL` is returned in case of @type being `G_VARIANT_TYPE_UNIT`. * - * This call, together with g_variant_type_next() provides an iterator + * This call, together with [method@GLib.VariantType.next] provides an iterator * interface over tuple and dictionary entry types. * - * Returns: (transfer none) (nullable): the first item type of @type, or %NULL + * Returns: (transfer none) (nullable): the first item type of @type, or `NULL` * if the type has no item types * Since 2.24 **/ @@ -972,23 +966,22 @@ g_variant_type_first (const GVariantType *type) /** * g_variant_type_next: - * @type: a #GVariantType from a previous call + * @type: a type from a previous call * * Determines the next item type of a tuple or dictionary entry * type. * * @type must be the result of a previous call to - * g_variant_type_first() or g_variant_type_next(). + * [method@GLib.VariantType.first] or [method@GLib.VariantType.next]. * * If called on the key type of a dictionary entry then this call * returns the value type. If called on the value type of a dictionary - * entry then this call returns %NULL. + * entry then this call returns `NULL`. * - * For tuples, %NULL is returned when @type is the last item in a tuple. + * For tuples, `NULL` is returned when @type is the last item in the tuple. * - * Returns: (transfer none) (nullable): the next type after @type, or %NULL if + * Returns: (transfer none) (nullable): the next type after @type, or `NULL` if * there are no further types - * * Since 2.24 **/ const GVariantType * @@ -1009,20 +1002,19 @@ g_variant_type_next (const GVariantType *type) /** * g_variant_type_n_items: - * @type: a tuple or dictionary entry #GVariantType + * @type: a tuple or dictionary entry type * * Determines the number of items contained in a tuple or * dictionary entry type. * * This function may only be used with tuple or dictionary entry types, * but must not be used with the generic tuple type - * %G_VARIANT_TYPE_TUPLE. + * `G_VARIANT_TYPE_TUPLE`. * * In the case of a dictionary entry type, this function will always - * return 2. + * return `2`. * * Returns: the number of items in @type - * * Since 2.24 **/ gsize @@ -1042,16 +1034,15 @@ g_variant_type_n_items (const GVariantType *type) /** * g_variant_type_key: - * @type: a dictionary entry #GVariantType + * @type: a dictionary entry type * * Determines the key type of a dictionary entry type. * * This function may only be used with a dictionary entry type. Other * than the additional restriction, this call is equivalent to - * g_variant_type_first(). + * [method@GLib.VariantType.first]. * * Returns: (transfer none): the key type of the dictionary entry - * * Since 2.24 **/ const GVariantType * @@ -1069,14 +1060,13 @@ g_variant_type_key (const GVariantType *type) /** * g_variant_type_value: - * @type: a dictionary entry #GVariantType + * @type: a dictionary entry type * * Determines the value type of a dictionary entry type. * * This function may only be used with a dictionary entry type. * * Returns: (transfer none): the value type of the dictionary entry - * * Since 2.24 **/ const GVariantType * @@ -1098,18 +1088,17 @@ g_variant_type_value (const GVariantType *type) /** * g_variant_type_new_tuple: - * @items: (array length=length): an array of #GVariantTypes, one for each item - * @length: the length of @items, or -1 + * @items: (array length=length): an array of types, one for each item + * @length: the length of @items, or `-1` * * Constructs a new tuple type, from @items. * - * @length is the number of items in @items, or -1 to indicate that - * @items is %NULL-terminated. + * @length is the number of items in @items, or `-1` to indicate that + * @items is `NULL`-terminated. * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new tuple #GVariantType + * It is appropriate to call [method@GLib.VariantType.free] on the return value. * + * Returns: (transfer full): a new tuple type * Since 2.24 **/ static GVariantType * @@ -1184,15 +1173,14 @@ g_variant_type_new_tuple (const GVariantType * const *items, /** * g_variant_type_new_array: (constructor) - * @element: a #GVariantType + * @element: an element type * * Constructs the type corresponding to an array of elements of the * type @type. * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new array #GVariantType + * It is appropriate to call [method@GLib.VariantType.first] on the return value. * + * Returns: (transfer full): a new array type * Since 2.24 **/ GVariantType * @@ -1214,15 +1202,14 @@ g_variant_type_new_array (const GVariantType *element) /** * g_variant_type_new_maybe: (constructor) - * @element: a #GVariantType + * @element: an element type * - * Constructs the type corresponding to a maybe instance containing - * type @type or Nothing. + * Constructs the type corresponding to a ‘maybe’ instance containing + * type @type or `Nothing`. * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new maybe #GVariantType + * It is appropriate to call [method@GLib.VariantType.free] on the return value. * + * Returns: (transfer full): a new ‘maybe’ type * Since 2.24 **/ GVariantType * @@ -1244,16 +1231,15 @@ g_variant_type_new_maybe (const GVariantType *element) /** * g_variant_type_new_dict_entry: (constructor) - * @key: a basic #GVariantType - * @value: a #GVariantType + * @key: a basic type to use for the key + * @value: a type to use for the value * * Constructs the type corresponding to a dictionary entry with a key * of type @key and a value of type @value. * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new dictionary entry #GVariantType + * It is appropriate to call [method@GLib.VariantType.free] on the return value. * + * Returns: (transfer full): a new dictionary entry type * Since 2.24 **/ GVariantType * diff --git a/glib/gvarianttype.h b/glib/gvarianttype.h index b105645da..38980af82 100644 --- a/glib/gvarianttype.h +++ b/glib/gvarianttype.h @@ -36,7 +36,7 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_BOOLEAN: * - * The type of a value that can be either %TRUE or %FALSE. + * The type of a value that can be either true or false. **/ #define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b") @@ -58,6 +58,7 @@ typedef struct _GVariantType GVariantType; * G_VARIANT_TYPE_UINT16: * * The type of an integer value that can range from 0 to 65535. + * * There were about this many people living in Toronto in the 1870s. **/ #define G_VARIANT_TYPE_UINT16 ((const GVariantType *) "q") @@ -74,7 +75,8 @@ typedef struct _GVariantType GVariantType; * G_VARIANT_TYPE_UINT32: * * The type of an integer value that can range from 0 to 4294967295. - * That's one number for everyone who was around in the late 1970s. + * + * That’s one number for everyone who was around in the late 1970s. **/ #define G_VARIANT_TYPE_UINT32 ((const GVariantType *) "u") @@ -90,18 +92,21 @@ typedef struct _GVariantType GVariantType; * G_VARIANT_TYPE_UINT64: * * The type of an integer value that can range from 0 - * to 18446744073709551615 (inclusive). That's a really big number, - * but a Rubik's cube can have a bit more than twice as many possible - * positions. + * to 18446744073709551615 (inclusive). + * + * That’s a really big number, but a Rubik’s cube can have a bit more than + * twice as many possible positions. **/ #define G_VARIANT_TYPE_UINT64 ((const GVariantType *) "t") /** * G_VARIANT_TYPE_DOUBLE: * - * The type of a double precision IEEE754 floating point number. - * These guys go up to about 1.80e308 (plus and minus) but miss out on - * some numbers in between. In any case, that's far greater than the + * The type of a double precision + * [IEEE 754 floating point number](https://en.wikipedia.org/wiki/IEEE_754). + * + * These go up to about 1.80e308 (plus and minus) but miss out on + * some numbers in between. In any case, that’s far greater than the * estimated number of fundamental particles in the observable * universe. **/ @@ -110,32 +115,39 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_STRING: * - * The type of a string. "" is a string. %NULL is not a string. + * The type of a string. + * + * `""` is a string. `NULL` is not a string. **/ #define G_VARIANT_TYPE_STRING ((const GVariantType *) "s") /** * G_VARIANT_TYPE_OBJECT_PATH: * - * The type of a D-Bus object reference. These are strings of a - * specific format used to identify objects at a given destination on - * the bus. + * The type of a + * [D-Bus object path](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path). + * + * These are strings of a specific format used to identify objects at a given + * destination on the bus. * * If you are not interacting with D-Bus, then there is no reason to make * use of this type. If you are, then the D-Bus specification contains a - * precise description of valid object paths. + * [precise description of valid object paths](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path). **/ #define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o") /** * G_VARIANT_TYPE_SIGNATURE: * - * The type of a D-Bus type signature. These are strings of a specific - * format used as type signatures for D-Bus methods and messages. + * The type of a + * [D-Bus type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system). + * + * These are strings of a specific format used as type signatures for D-Bus + * methods and messages. * * If you are not interacting with D-Bus, then there is no reason to make * use of this type. If you are, then the D-Bus specification contains a - * precise description of valid signature strings. + * [precise description of valid signature strings](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system). **/ #define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g") @@ -150,7 +162,7 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_HANDLE: * - * The type of a 32bit signed integer value, that by convention, is used + * The type of a 32-bit signed integer value, that by convention, is used * as an index into an array of file descriptors that are sent alongside * a D-Bus message. * @@ -162,8 +174,9 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_UNIT: * - * The empty tuple type. Has only one instance. Known also as "triv" - * or "void". + * The empty tuple type. + * + * Has only one instance. Known also as ‘triv’ or ‘void’. **/ #define G_VARIANT_TYPE_UNIT ((const GVariantType *) "()") @@ -186,7 +199,7 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_MAYBE: * - * An indefinite type that is a supertype of every maybe type. + * An indefinite type that is a supertype of every ‘maybe’ type. **/ #define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*") @@ -216,7 +229,7 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_DICTIONARY: * - * An indefinite type that is a supertype of every dictionary type -- + * An indefinite type that is a supertype of every dictionary type — * that is, any array type that has an element type equal to any * dictionary entry type. **/ @@ -239,8 +252,10 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE_BYTESTRING: * - * The type of an array of bytes. This type is commonly used to pass - * around strings that may not be valid utf8. In that case, the + * The type of an array of bytes. + * + * This type is commonly used to pass around strings that may not be valid + * UTF-8, such as file system paths. In that case, the * convention is that the nul terminator character should be included as * the last character in the array. **/ @@ -257,7 +272,7 @@ typedef struct _GVariantType GVariantType; * G_VARIANT_TYPE_VARDICT: * * The type of a dictionary mapping strings to variants (the ubiquitous - * "a{sv}" type). + * `a{sv}` type). * * Since: 2.30 **/ @@ -266,14 +281,15 @@ typedef struct _GVariantType GVariantType; /** * G_VARIANT_TYPE: - * @type_string: a well-formed #GVariantType type string + * @type_string: a well-formed [type@GLib.VariantType] type string * - * Converts a string to a const #GVariantType. Depending on the - * current debugging level, this function may perform a runtime check - * to ensure that @string is a valid GVariant type string. + * Converts a string to a const [type@GLib.VariantType]. + * + * Depending on the current debugging level, this function may perform a runtime + * check to ensure that @string is a valid [type@GLib.Variant] type string. * * It is always a programmer error to use this macro with an invalid - * type string. If in doubt, use g_variant_type_string_is_valid() to + * type string. If in doubt, use [func@GLib.variant_type_string_is_valid] to * check if the string is valid. * * Since 2.24