[gnome-software: 46/72] docs: Make refine asynchronous

[Philip Withnall <pwithnall src gnome org>]

commit 43a9b7c856ac94e70c4382ef1f1862b22984750a
Author: Philip Withnall <pwithnall endlessos org>
Date:   Tue Nov 23 17:33:20 2021 +0000

    docs: Make refine asynchronous
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #1472

 doc/api/gnome-software-docs.xml | 42 +++++++++++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 12 deletions(-)
---
diff --git a/doc/api/gnome-software-docs.xml b/doc/api/gnome-software-docs.xml
index 6f5b77b75..4720dcb91 100644
--- a/doc/api/gnome-software-docs.xml
+++ b/doc/api/gnome-software-docs.xml
@@ -320,7 +320,7 @@ gs_plugin_add_installed (GsPlugin *plugin,
 
         <para>
           By filling in the optional details (which can also be filled in using
-          <code>gs_plugin_refine()</code> you can also make the details
+          <code>refine_async()</code> you can also make the details
           page a much more exciting place.
           Adding a set of screenshots is left as an exercise to the reader.
         </para>
@@ -447,30 +447,48 @@ gs_plugin_refresh (GsPlugin *plugin,
         <example>
           <title>Refine example</title>
           <programlisting>
-gboolean
-gs_plugin_refine (GsPlugin *plugin,
-                  GsAppList *list,
-                  GsPluginRefineFlags flags,
-                  GCancellable *cancellable,
-                  GError **error)
+static void
+gs_plugin_example_refine_async (GsPlugin *plugin,
+                                GsAppList *list,
+                                GsPluginRefineFlags flags,
+                                GCancellable *cancellable,
+                                GAsyncReadyCallback callback,
+                                gpointer user_data)
 {
+  g_autoptr(GTask) task = NULL;
+
+  task = g_task_new (plugin, cancellable, callback, user_data);
+  g_task_set_source_tag (task, gs_plugin_example_refine_async);
+
   /* not required */
-  if ((flags &amp; GS_PLUGIN_REFINE_FLAGS_REQUIRE_LICENSE) == 0)
-    return TRUE;
+  if ((flags &amp; GS_PLUGIN_REFINE_FLAGS_REQUIRE_LICENSE) == 0) {
+    g_task_return_boolean (task, TRUE);
+    return;
+  }
 
   for (guint i = 0; i &lt; gs_app_list_length (list); i++) {
     GsApp *app = gs_app_list_index (list, i);
 
     /* already set */
-    if (gs_app_get_license (app) != NULL)
-      return TRUE;
+    if (gs_app_get_license (app) != NULL) {
+      g_task_return_boolean (task, TRUE);
+      return;
+    }
 
     /* FIXME, not just hardcoded! */
     if (g_strcmp0 (gs_app_get_id (app, "chiron.desktop") == 0))
       gs_app_set_license (app, "GPL-2.0 and LGPL-2.0+");
   }
 
-  return TRUE;
+  g_task_return_boolean (task, TRUE);
+}
+
+static gboolean
+gs_plugin_example_refine_finish (GsPlugin *plugin,
+                                 GAsyncResult *result,
+                                 GError **error)
+{
+  return g_task_propagate_boolean (G_TASK (result), error);
 }
           </programlisting>
         </example>