[glib: 1/5] gicon: Add introspection for to_tokens / from_tokens vfunc's

[Philip Withnall <pwithnall src gnome org>]

commit 19cfc55847e694849080c88f824bdf2ab0d4d606
Author: Marco Trevisan (Treviño) <mail 3v1n0 net>
Date:   Mon Oct 3 21:37:00 2022 +0200

    gicon: Add introspection for to_tokens / from_tokens vfunc's
    
    The GIconIface virtual functions were not introspectable as they use
    complex parameters that GI isn't able to compute alone.
    
    So provide introspection metadata to the two function pointers
    definitions.
    
    GIcon::from_tokens is a static virtual function so it won't actually
    work until GI support for it [1] is merged.
    
    [1] https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/361

 gio/gicon.h | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)
---
diff --git a/gio/gicon.h b/gio/gicon.h
index 22e7e5ef51..2f224c10fe 100644
--- a/gio/gicon.h
+++ b/gio/gicon.h
@@ -69,9 +69,38 @@ struct _GIconIface
   guint       (* hash)        (GIcon   *icon);
   gboolean    (* equal)       (GIcon   *icon1,
                                GIcon   *icon2);
+
+  /**
+   * GIconIface::to_tokens:
+   * @icon: The #GIcon
+   * @tokens: (element-type utf8) (out caller-allocates):
+   *   The array to fill with tokens
+   * @out_version: (out): version of serialized tokens
+   *
+   * Serializes the @icon into string tokens.
+   * This is can be invoked when g_icon_new_for_string() is called.
+   *
+   * Returns: %TRUE if serialization took place, %FALSE otherwise
+   *
+   * Since: 2.20
+   */
   gboolean    (* to_tokens)   (GIcon   *icon,
-                              GPtrArray *tokens,
+                               GPtrArray *tokens,
                                gint    *out_version);
+
+  /**
+   * GIconIface::from_tokens:
+   * @tokens: (array length=num_tokens): An array of tokens
+   * @num_tokens: The number of tokens in @tokens
+   * @version: Version of the serialized tokens
+   * @error: Return location for errors, or %NULL to ignore
+   *
+   * Constructs a #GIcon from a list of @tokens.
+   *
+   * Returns: (nullable) (transfer full): the #GIcon or %NULL on error
+   *
+   * Since: 2.20
+   */
   GIcon *     (* from_tokens) (gchar  **tokens,
                                gint     num_tokens,
                                gint     version,