luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-28 16:36:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'gvarianttype-docs' into 'main'

Browse Source 
gvarianttype: Add two missing (nullable) annotations and port docs to gi-docgen format

See merge request GNOME/glib!4326
This commit is contained in:
Philip Withnall 2024-10-19 00:44:46 +00:00
commit b465ca1e9e
2 changed files with 193 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

309
glib/gvarianttype.c
View File

@ -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,25 +927,25 @@ 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): 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 *
@ -972,22 +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.
*
* Returns: (transfer none): the next #GVariantType after @type, or %NULL
* 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
* there are no further types
* Since 2.24
**/
const GVariantType *
@ -1008,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
@ -1041,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 *
@ -1068,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 *
@ -1097,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 *
@ -1183,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 *
@ -1213,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 *
@ -1243,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 *

74
glib/gvarianttype.h
View File

@ -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