GNOME.org
 

[gnome-software] Fix docstrings

commit ad445a290919a363805b10e2f3748391470d4ef5
Author: Robert Ancell <robert ancell canonical com>
Date:   Wed Aug 29 21:42:11 2018 +1200

    Fix docstrings

 lib/gs-app-list.c      |  1 +
 lib/gs-app.c           |  2 +-
 lib/gs-app.h           |  2 +-
 lib/gs-category.c      |  1 -
 lib/gs-plugin-loader.c | 21 +++++++++++++++++++++
 lib/gs-plugin-loader.h |  4 ++--
 lib/gs-plugin-types.h  |  1 +
 lib/gs-plugin-vfuncs.h |  6 ++++--
 lib/gs-plugin.c        | 16 +++++++++++-----
 lib/gs-utils.c         |  3 ++-
 lib/gs-utils.h         |  2 ++
 11 files changed, 46 insertions(+), 13 deletions(-)
---
diff --git a/lib/gs-app-list.c b/lib/gs-app-list.c
index 4d39a5c2..f30932ab 100644
--- a/lib/gs-app-list.c
+++ b/lib/gs-app-list.c
@@ -575,6 +575,7 @@ gs_app_list_sort_cb (gconstpointer a, gconstpointer b, gpointer user_data)
  * gs_app_list_sort:
  * @list: A #GsAppList
  * @func: A #GCompareFunc
+ * @user_data: user data to pass to @func
  *
  * Sorts the application list.
  *
diff --git a/lib/gs-app.c b/lib/gs-app.c
index 815d2e24..805c6894 100644
--- a/lib/gs-app.c
+++ b/lib/gs-app.c
@@ -1050,7 +1050,7 @@ gs_app_set_progress (GsApp *app, guint percentage)
 /**
  * gs_app_set_allow_cancel:
  * @app: a #GsApp
- * @boolean: if the installation or upgrade can be cancelled or not
+ * @allow_cancel: if the installation or upgrade can be cancelled or not
  *
  * This sets a flag indicating whether the operation can be cancelled or not.
  * This is used by the UI to set the "Cancel" button insensitive as
diff --git a/lib/gs-app.h b/lib/gs-app.h
index 9cb2bc55..f05779a2 100644
--- a/lib/gs-app.h
+++ b/lib/gs-app.h
@@ -138,7 +138,7 @@ void                 gs_app_set_progress            (GsApp          *app,
                                                 guint           percentage);
 gboolean       gs_app_get_allow_cancel         (GsApp  *app);
 void           gs_app_set_allow_cancel          (GsApp *app,
-                                                 gboolean      can_cancel);
+                                                 gboolean      allow_cancel);
 const gchar    *gs_app_get_unique_id           (GsApp          *app);
 const gchar    *gs_app_get_branch              (GsApp          *app);
 void            gs_app_set_branch              (GsApp          *app,
diff --git a/lib/gs-category.c b/lib/gs-category.c
index 8d892bdf..599f615a 100644
--- a/lib/gs-category.c
+++ b/lib/gs-category.c
@@ -562,7 +562,6 @@ gs_category_init (GsCategory *category)
 /**
  * gs_category_new:
  * @id: an ID, e.g. "all"
- * @name: a localised name
  *
  * Creates a new category object.
  *
diff --git a/lib/gs-plugin-loader.c b/lib/gs-plugin-loader.c
index 02be77ba..e26b8531 100644
--- a/lib/gs-plugin-loader.c
+++ b/lib/gs-plugin-loader.c
@@ -1481,6 +1481,9 @@ gs_plugin_loader_convert_unavailable (GsAppList *list, const gchar *search)
 
 /**
  * gs_plugin_loader_job_process_finish:
+ * @plugin_loader: A #GsPluginLoader
+ * @res: a #GAsyncResult
+ * @error: A #GError, or %NULL
  *
  * Return value: (element-type GsApp) (transfer full): A list of applications
  **/
@@ -1500,6 +1503,9 @@ gs_plugin_loader_job_process_finish (GsPluginLoader *plugin_loader,
 
 /**
  * gs_plugin_loader_job_action_finish:
+ * @plugin_loader: A #GsPluginLoader
+ * @res: a #GAsyncResult
+ * @error: A #GError, or %NULL
  *
  * Return value: success
  **/
@@ -1613,6 +1619,11 @@ gs_plugin_loader_job_get_categories_thread_cb (GTask *task,
 
 /**
  * gs_plugin_loader_job_get_categories_async:
+ * @plugin_loader: A #GsPluginLoader
+ * @plugin_job: job to process
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: function to call when complete
+ * @user_data: user data to pass to @callback
  *
  * This method calls all plugins that implement the gs_plugin_add_categories()
  * function. The plugins return #GsCategory objects.
@@ -1643,6 +1654,9 @@ gs_plugin_loader_job_get_categories_async (GsPluginLoader *plugin_loader,
 
 /**
  * gs_plugin_loader_job_get_categories_finish:
+ * @plugin_loader: A #GsPluginLoader
+ * @res: a #GAsyncResult
+ * @error: A #GError, or %NULL
  *
  * Return value: (element-type GsCategory) (transfer full): A list of applications
  **/
@@ -3484,6 +3498,11 @@ gs_plugin_loader_schedule_task (GsPluginLoader *plugin_loader,
 
 /**
  * gs_plugin_loader_job_process_async:
+ * @plugin_loader: A #GsPluginLoader
+ * @plugin_job: job to process
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: function to call when complete
+ * @user_data: user data to pass to @callback
  *
  * This method calls all plugins.
  **/
@@ -3702,6 +3721,8 @@ gs_plugin_loader_job_process_async (GsPluginLoader *plugin_loader,
 
 /**
  * gs_plugin_loader_get_plugin_supported:
+ * @plugin_loader: A #GsPluginLoader
+ * @function_name: a function name
  *
  * This function returns TRUE if the symbol is found in any enabled plugin.
  */
diff --git a/lib/gs-plugin-loader.h b/lib/gs-plugin-loader.h
index a58502d5..1b5b754e 100644
--- a/lib/gs-plugin-loader.h
+++ b/lib/gs-plugin-loader.h
@@ -90,7 +90,7 @@ gboolean       gs_plugin_loader_get_allow_updates     (GsPluginLoader *plugin_loader);
 gboolean        gs_plugin_loader_get_network_available (GsPluginLoader *plugin_loader);
 gboolean        gs_plugin_loader_get_network_metered   (GsPluginLoader *plugin_loader);
 gboolean        gs_plugin_loader_get_plugin_supported  (GsPluginLoader *plugin_loader,
-                                                        const gchar    *plugin_func);
+                                                        const gchar    *function_name);
 
 GPtrArray      *gs_plugin_loader_get_events            (GsPluginLoader *plugin_loader);
 GsPluginEvent  *gs_plugin_loader_get_event_default     (GsPluginLoader *plugin_loader);
@@ -107,7 +107,7 @@ void                 gs_plugin_loader_clear_caches          (GsPluginLoader 
*plugin_loader);
 GsPlugin       *gs_plugin_loader_find_plugin           (GsPluginLoader *plugin_loader,
                                                         const gchar    *plugin_name);
 void            gs_plugin_loader_set_max_parallel_ops  (GsPluginLoader *plugin_loader,
-                                                        guint           num_ops);
+                                                        guint           max_ops);
 
 
 G_END_DECLS
diff --git a/lib/gs-plugin-types.h b/lib/gs-plugin-types.h
index 9c088dfc..14dfdffc 100644
--- a/lib/gs-plugin-types.h
+++ b/lib/gs-plugin-types.h
@@ -246,6 +246,7 @@ typedef enum {
  * @GS_PLUGIN_ACTION_AUTH_LOST_PASSWORD:       Authentication lost password action
  * @GS_PLUGIN_ACTION_URL_TO_APP:               Convert the file to an application
  * @GS_PLUGIN_ACTION_GET_RECENT:               Get the apps recently released
+ * @GS_PLUGIN_ACTION_GET_UPDATES_HISTORICAL:    Get the list of historical updates
  * @GS_PLUGIN_ACTION_INITIALIZE:               Initialize the plugin
  * @GS_PLUGIN_ACTION_DESTROY:                  Destroy the plugin
  * @GS_PLUGIN_ACTION_PURCHASE:                 Purchase an app
diff --git a/lib/gs-plugin-vfuncs.h b/lib/gs-plugin-vfuncs.h
index b4fedbdf..fcf53a98 100644
--- a/lib/gs-plugin-vfuncs.h
+++ b/lib/gs-plugin-vfuncs.h
@@ -268,7 +268,7 @@ gboolean     gs_plugin_add_updates_historical       (GsPlugin       *plugin,
 /**
  * gs_plugin_add_categories:
  * @plugin: a #GsPlugin
- * @list (element-type GsCategory): a #GPtrArray
+ * @list: (element-type GsCategory): a #GPtrArray
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
  *
@@ -286,7 +286,8 @@ gboolean     gs_plugin_add_categories               (GsPlugin       *plugin,
 /**
  * gs_plugin_add_category_apps:
  * @plugin: a #GsPlugin
- * @category: a #GsCategory * @list: a #GsAppList
+ * @category: a #GsCategory
+ * @list: a #GsAppList
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
  *
@@ -305,6 +306,7 @@ gboolean     gs_plugin_add_category_apps            (GsPlugin       *plugin,
 /**
  * gs_plugin_add_recent:
  * @plugin: a #GsPlugin
+ * @list: a #GsAppList
  * @age: a number of seconds
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
diff --git a/lib/gs-plugin.c b/lib/gs-plugin.c
index 8b997b98..ad8d66e7 100644
--- a/lib/gs-plugin.c
+++ b/lib/gs-plugin.c
@@ -376,8 +376,9 @@ gs_plugin_action_stop (GsPlugin *plugin)
 }
 
 /**
- * gs_plugin_get_symbol (skip):
+ * gs_plugin_get_symbol: (skip)
  * @plugin: a #GsPlugin
+ * @function_name: a symbol name
  *
  * Gets the symbol from the module that backs the plugin. If the plugin is not
  * enabled then no symbol is returned.
@@ -499,7 +500,7 @@ gs_plugin_get_appstream_id (GsPlugin *plugin)
 }
 
 /**
- * gs_plugin_get_appstream_id:
+ * gs_plugin_set_appstream_id:
  * @plugin: a #GsPlugin
  * @appstream_id: an appstream ID, e.g. `org.gnome.Software.Plugin.Epiphany`
  *
@@ -815,7 +816,7 @@ gs_plugin_set_soup_session (GsPlugin *plugin, SoupSession *soup_session)
 /**
  * gs_plugin_set_network_monitor:
  * @plugin: a #GsPlugin
- * @network_monitor: a #GNetworkMonitor
+ * @monitor: a #GNetworkMonitor
  *
  * Sets the network monitor so that plugins can check the state of the network.
  *
@@ -1028,12 +1029,16 @@ void
 gs_plugin_status_update (GsPlugin *plugin, GsApp *app, GsPluginStatus status)
 {
        GsPluginStatusHelper *helper;
+       g_autoptr(GSource) idle_source = NULL;
+
        helper = g_slice_new0 (GsPluginStatusHelper);
        helper->plugin = plugin;
        helper->status = status;
        if (app != NULL)
                helper->app = g_object_ref (app);
-       g_idle_add (gs_plugin_status_update_cb, helper);
+       idle_source = g_idle_source_new ();
+       g_source_set_callback (idle_source, gs_plugin_status_update_cb, helper, NULL);
+       g_source_attach (idle_source, NULL);
 }
 
 static gboolean
@@ -1424,6 +1429,7 @@ gs_plugin_download_rewrite_resource_uri (GsPlugin *plugin,
 /**
  * gs_plugin_download_rewrite_resource:
  * @plugin: a #GsPlugin
+ * @app: a #GsApp, or %NULL
  * @resource: the CSS resource
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
@@ -2003,7 +2009,7 @@ gs_plugin_action_from_string (const gchar *action)
 
 /**
  * gs_plugin_refine_flags_to_string:
- * @action: some #GsPluginRefineFlags, e.g. %GS_PLUGIN_REFINE_FLAGS_REQUIRE_SIZE
+ * @refine_flags: some #GsPluginRefineFlags, e.g. %GS_PLUGIN_REFINE_FLAGS_REQUIRE_SIZE
  *
  * Converts the flags to a string.
  *
diff --git a/lib/gs-utils.c b/lib/gs-utils.c
index 6ed5d5ae..23d24995 100644
--- a/lib/gs-utils.c
+++ b/lib/gs-utils.c
@@ -606,7 +606,6 @@ gs_utils_error_add_unique_id (GError **error, GsApp *app)
 /**
  * gs_utils_error_strip_unique_id:
  * @error: a #GError
- * @app: a #GsApp
  *
  * Removes a possible unique ID prefix from the error.
  *
@@ -1029,6 +1028,7 @@ gs_utils_append_key_value (GString *str, gsize align_len,
 
 /**
  * gs_utils_is_low_resolution:
+ * @toplevel: widget on monitor to check
  *
  * Retrieves whether the primary monitor has a low resolution.
  *
@@ -1067,6 +1067,7 @@ gs_utils_get_memory_total (void)
 
 /**
  * gs_utils_parse_evr:
+ * @evr: an EVR version string
  * @out_epoch: (out): return location for the epoch string
  * @out_version: (out): return location for the version string
  * @out_release: (out): return location for the release string
diff --git a/lib/gs-utils.h b/lib/gs-utils.h
index 944b9ee9..6fb98ff1 100644
--- a/lib/gs-utils.h
+++ b/lib/gs-utils.h
@@ -34,6 +34,8 @@ G_BEGIN_DECLS
  * GsUtilsCacheFlags:
  * @GS_UTILS_CACHE_FLAG_NONE:          No flags set
  * @GS_UTILS_CACHE_FLAG_WRITEABLE:     A writable directory is required
+ * @GS_UTILS_CACHE_FLAG_USE_HASH:      Prefix a hash to the filename
+ * @GS_UTILS_CACHE_FLAG_ENSURE_EMPTY:  Clear existing cached items
  *
  * The cache flags.
  **/
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]