Merge branch 'wip/jtojnar/variant-docs' into 'main'

docs: Minor GVariant fixes

See merge request GNOME/glib!4011

docs/reference/glib/gvariant-format-strings.md

@@ -73,9 +73,10 @@ The equivalent C types are as follows:
 | `u`       | `guint32`         |
 | `x`       | `gint64`          |
 | `t`       | `guint64`         |
-| `h`       | `gint32`          |
+| `h`       | `gint32` (handle) |
 | `d`       | `gdouble`         |
 
+<a id="varargs"></a>
 Note that in C, small integer types in variable argument lists are promoted
 up to `int` or `unsigned int` as appropriate, and read back accordingly. `int`
 is 32 bits on every platform on which GLib is currently supported. This

docs/reference/glib/gvariant-specification-1.0.rst

@@ -22,6 +22,9 @@ and diffs, see the `commit log <https://gitlab.gnome.org/GNOME/glib/-/blob/main/
 **Version 1.0.1, 2022-11-02**
    - Formatting improvements
    - No semantic changes
+**Version 1.0.2, 2024-04-16**
+   - Add missing references to ``h`` type string
+   - Add missing reference to ``d`` type string to type string grammar
 
 *****
 Types
@@ -171,7 +174,7 @@ that is used by the recursive structure of the language itself.
 Type strings can be described by a non-ambiguous context free grammar.
 
  * *type* ⇒ *base_type* | *container_type*
- * *base_type* ⇒ **b** | **y** | **n** | **q** | **i** | **u** | **x** | **t** | **s** | **o** | **g**
+ * *base_type* ⇒ **b** | **y** | **n** | **q** | **i** | **u** | **x** | **t** | **h** | **d** | **s** | **o** | **g**
  * *container_type* ⇒ **v** | **m** *type* | **a** *type* | **(** *types* **)** | **{** *base_type* *type* **}**
  * *types* ⇒ ε | *type* *types*
 
@@ -198,6 +201,8 @@ term containing a terminal is specified below:
    This derivation corresponds to the signed 64-bit integer type.
 **t**
    This derivation corresponds to the unsigned 64-bit integer type.
+**h**
+   This derivation corresponds to the signed 32-bit integer type, representing a handle.
 **d**
    This derivation corresponds to the double precision floating point number type.
 **s**

gio/gactionmap.c

@@ -135,7 +135,7 @@ g_action_map_remove_action (GActionMap  *action_map,
  *                  activate function for this action, given as a single
  *                  GVariant type string (or %NULL for no parameter)
  * @state: the initial state for this action, given in
- *         [GVariant text format][gvariant-text].  The state is parsed
+ *         [GVariant text format](gvariant-text-format.html).  The state is parsed
  *         with no extra type information, so type tags must be added to
  *         the string if they are necessary.  Stateless actions should
  *         give %NULL here.

glib/gvariant-parser.c

@@ -2587,7 +2587,7 @@ g_variant_parse (const GVariantType  *type,
  *
  * Note that the arguments in @app must be of the correct width for their types
  * specified in @format when collected into the #va_list. See
- * the [GVariant varargs documentation][gvariant-varargs].
+ * the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * In order to behave correctly in all cases it is necessary for the
  * calling function to g_variant_ref_sink() the return result before
@@ -2646,7 +2646,7 @@ g_variant_new_parsed_va (const gchar *format,
  *
  * Note that the arguments must be of the correct width for their types
  * specified in @format. This can be achieved by casting them. See
- * the [GVariant varargs documentation][gvariant-varargs].
+ * the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * Consider this simple example:
  * |[<!-- language="C" --> 
@@ -2699,7 +2699,7 @@ g_variant_new_parsed (const gchar *format,
  *
  * Note that the arguments must be of the correct width for their types
  * specified in @format_string. This can be achieved by casting them. See
- * the [GVariant varargs documentation][gvariant-varargs].
+ * the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * This function might be used as follows:
  *

glib/gvariant.c

@@ -1112,7 +1112,7 @@ g_variant_lookup_value (GVariant           *dictionary,
  *
  * @element_size must be the size of a single element in the array,
  * as given by the section on
- * [serialized data memory][gvariant-serialized-data-memory].
+ * [serialized data memory](struct.Variant.html#serialized-data-memory).
  *
  * In particular, arrays of these fixed-sized types can be interpreted
  * as an array of the given C type, with @element_size set to the size
@@ -1258,7 +1258,7 @@ g_variant_new_fixed_array (const GVariantType  *element_type,
  *
  * @string must be valid UTF-8, and must not be %NULL. To encode
  * potentially-%NULL strings, use g_variant_new() with `ms` as the
- * [format string][gvariant-format-strings-maybe-types].
+ * [format string](gvariant-format-strings.html#maybe-types).
  *
  * Returns: (transfer none): a floating reference to a new string #GVariant instance
  *
@@ -2641,7 +2641,7 @@ g_variant_print_string (GVariant *value,
  *
  * Pretty-prints @value in the format understood by g_variant_parse().
  *
- * The format is described [here][gvariant-text].
+ * The format is described [here](gvariant-text-format.html).
  *
  * If @type_annotate is %TRUE, then type information is included in
  * the output.
@@ -4361,7 +4361,7 @@ g_variant_dict_unref (GVariantDict *dict)
  * not be accessed and the effect is otherwise equivalent to if the
  * character at @limit were nul.
  *
- * See the section on [GVariant format strings][gvariant-format-strings].
+ * See the section on [GVariant format strings](gvariant-format-strings.html).
  *
  * Returns: %TRUE if there was a valid format string
  *
@@ -5376,7 +5376,7 @@ g_variant_valist_get (const gchar **str,
  *
  * The type of the created instance and the arguments that are expected
  * by this function are determined by @format_string. See the section on
- * [GVariant format strings][gvariant-format-strings]. Please note that
+ * [GVariant format strings](gvariant-format-strings.html). Please note that
  * the syntax of the format string is very likely to be extended in the
  * future.
  *
@@ -5386,7 +5386,7 @@ g_variant_valist_get (const gchar **str,
  *
  * Note that the arguments must be of the correct width for their types
  * specified in @format_string. This can be achieved by casting them. See
- * the [GVariant varargs documentation][gvariant-varargs].
+ * the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * |[<!-- language="C" -->
  * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
@@ -5447,7 +5447,7 @@ g_variant_new (const gchar *format_string,
  *
  * Note that the arguments in @app must be of the correct width for their
  * types specified in @format_string when collected into the #va_list.
- * See the [GVariant varargs documentation][gvariant-varargs].
+ * See the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * These two generalisations allow mixing of multiple calls to
  * g_variant_new_va() and g_variant_get_va() within a single actual
@@ -5503,7 +5503,7 @@ g_variant_new_va (const gchar  *format_string,
  * determined by @format_string.  @format_string also restricts the
  * permissible types of @value.  It is an error to give a value with
  * an incompatible type.  See the section on
- * [GVariant format strings][gvariant-format-strings].
+ * [GVariant format strings](gvariant-format-strings.html).
  * Please note that the syntax of the format string is very likely to be
  * extended in the future.
  *
@@ -5603,7 +5603,7 @@ g_variant_get_va (GVariant     *value,
  *
  * Note that the arguments must be of the correct width for their types
  * specified in @format_string. This can be achieved by casting them. See
- * the [GVariant varargs documentation][gvariant-varargs].
+ * the [GVariant varargs documentation](gvariant-format-strings.html#varargs).
  *
  * This function might be used as follows:
  *