Merge branch 'gicon-introspect-vfuncs' into 'main'

gicon: Add introspection for to_tokens / from_tokens vfunc's

See merge request GNOME/glib!2937

gio/gicon.c

@@ -85,7 +85,7 @@ g_icon_default_init (GIconInterface *iface)
 
 /**
  * g_icon_hash:
- * @icon: (not nullable): #gconstpointer to an icon object.
+ * @icon: (not nullable) (type Gio.Icon): #gconstpointer to an icon object.
  * 
  * Gets a hash for an icon.
  *
@@ -106,7 +106,7 @@ g_icon_hash (gconstpointer icon)
 }
 
 /**
- * g_icon_equal:
+ * g_icon_equal: (virtual equal)
  * @icon1: (nullable): pointer to the first #GIcon.
  * @icon2: (nullable): pointer to the second #GIcon.
  * 
@@ -204,7 +204,6 @@ g_icon_to_string_tokenized (GIcon *icon, GString *s)
  * - If @icon is a #GThemedIcon with exactly one name and no fallbacks,
  *   the encoding is simply the name (such as `network-server`).
  *
- * Virtual: to_tokens
  * Returns: (nullable): An allocated NUL-terminated UTF8 string or
  * %NULL if @icon can't be serialized. Use g_free() to free.
  *
@@ -646,7 +645,7 @@ g_icon_deserialize (GVariant *value)
 }
 
 /**
- * g_icon_serialize:
+ * g_icon_serialize: (virtual serialize)
  * @icon: a #GIcon
  *
  * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved

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,