mcp: fix a bunch of doc warnings

3 files changed, 26 insertions, 20 deletions

diff --git a/mission-control-plugins/account-storage.c b/mission-control-plugins/account-storage.c
index 354f121e..6475ef84 100644
--- a/mission-control-plugins/account-storage.c
+++ b/mission-control-plugins/account-storage.c
@@ -334,7 +334,7 @@ mcp_account_storage_iface_implement_get_restrictions (
  * mcp_account_storage_priority:
  * @storage: an #McpAccountStorage instance
  *
- * Returns a #gint indicating the priority of the plugin.
+ * Gets the priority for this plugin.
  *
  * Priorities currently run from MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT
  * (the default storage plugin priority) upwards.
@@ -361,6 +361,8 @@ mcp_account_storage_iface_implement_get_restrictions (
  * to lowest, with the first plugin that claims a setting being assigned
  * ownership, and all lower priority plugins being asked to delete the
  * setting in question.
+ *
+ * Returns: the priority of this plugin
  **/
 gint
 mcp_account_storage_priority (const McpAccountStorage *storage)
@@ -389,7 +391,7 @@ mcp_account_storage_priority (const McpAccountStorage *storage)
  * into the account manager via @am. The return value in this case should
  * be %TRUE if any settings were found.
  *
- * Returns: a #gboolean - %TRUE if a value was found and %FALSE otherwise
+ * Returns: %TRUE if a value was found and %FALSE otherwise
  */
 gboolean
 mcp_account_storage_get (const McpAccountStorage *storage,
@@ -420,21 +422,21 @@ mcp_account_storage_get (const McpAccountStorage *storage,
  * The plugin is not expected to write to its long term storage
  * at this point.
  *
- * Returns: a #gboolean - %TRUE if the setting was claimed, %FALSE otherwise
+ * Returns: %TRUE if the setting was claimed, %FALSE otherwise
  */
 gboolean
 mcp_account_storage_set (const McpAccountStorage *storage,
     const McpAccountManager *am,
     const gchar *account,
     const gchar *key,
-    const gchar *val)
+    const gchar *value)
 {
   McpAccountStorageIface *iface = MCP_ACCOUNT_STORAGE_GET_IFACE (storage);
 
   SDEBUG (storage, "");
   g_return_val_if_fail (iface != NULL, FALSE);
 
-  return iface->set (storage, am, account, key, val);
+  return iface->set (storage, am, account, key, value);
 }
 
 /**
@@ -455,7 +457,7 @@ mcp_account_storage_set (const McpAccountStorage *storage,
  * The plugin is not expected to update its long term storage at
  * this point.
  *
- * Returns: a #gboolean - %TRUE if the setting or settings are not
+ * Returns: %TRUE if the setting or settings are not
  * the plugin's cache after this operation, %FALSE otherwise.
  * This is very unlikely to ever be %FALSE, as a plugin is always
  * expected to be able to manipulate its own cache.
@@ -491,8 +493,9 @@ mcp_account_storage_delete (const McpAccountStorage *storage,
  * implemented but @commit is not, @commit_one will be called with
  * @account_name = %NULL to commit all accounts.
  *
- * Returns: a gboolean - normally %TRUE, %FALSE if there was a problem
- * that was immediately obvious.
+ * Returns: %TRUE if the commit process was started (but not necessarily
+ * completed) successfully; %FALSE if there was a problem that was immediately
+ * obvious.
  */
 gboolean
 mcp_account_storage_commit (const McpAccountStorage *storage,
@@ -530,8 +533,9 @@ mcp_account_storage_commit (const McpAccountStorage *storage,
  * account. This is optional to implement; the default implementation
  * is to call @commit.
  *
- * Returns: a gboolean - normally %TRUE, %FALSE if there was a problem
- * that was immediately obvious.
+ * Returns: %TRUE if the commit process was started (but not necessarily
+ * completed) successfully; %FALSE if there was a problem that was immediately
+ * obvious.
  */
 gboolean
 mcp_account_storage_commit_one (const McpAccountStorage *storage,
@@ -558,9 +562,10 @@ mcp_account_storage_commit_one (const McpAccountStorage *storage,
  * This method is called only at initialisation time, before the dbus name
  * has been claimed, and is the only one permitted to block.
  *
- * Returns: a #GList of #gchar* (the unique account names) that the plugin
- * has settings for. The #GList (and its contents) should be freed when the
- * caller is done with them.
+ * Returns: (element-type utf8) (transfer full): a list of account names that
+ * the plugin has settings for. The account names should be freed with
+ * g_free(), and the list with g_list_free(), when the caller is done with
+ * them.
  **/
 GList *
 mcp_account_storage_list (const McpAccountStorage *storage,
@@ -577,6 +582,7 @@ mcp_account_storage_list (const McpAccountStorage *storage,
 /**
  * mcp_account_storage_ready:
  * @storage: an #McpAccountStorage instance
+ * @am: an #McpAccountManager instance
  *
  * Informs the plugin that it is now permitted to create new accounts,
  * ie it can now fire its "created", "altered", "toggled" and "deleted"
@@ -638,8 +644,8 @@ mcp_account_storage_get_identifier (const McpAccountStorage *storage,
  * Return additional storage-specific information about this account, which is
  * made available on D-Bus but not otherwise interpreted by Mission Control.
  *
- * Returns: a caller owned #GHashTable mapping with string keys and #GValue
- * values.
+ * Returns: a mapping from strings to #GValue<!-- -->s, which must be freed by
+ * the caller.
  */
 GHashTable *
 mcp_account_storage_get_additional_info (const McpAccountStorage *storage,
@@ -687,7 +693,7 @@ mcp_account_storage_get_restrictions (const McpAccountStorage *storage,
  * mcp_account_storage_name:
  * @storage: an #McpAccountStorage instance
  *
- * Returns: a const #gchar* : the plugin's name (for logging etc)
+ * Returns: the plugin's name (for logging etc)
  */
 const gchar *
 mcp_account_storage_name (const McpAccountStorage *storage)
@@ -703,7 +709,7 @@ mcp_account_storage_name (const McpAccountStorage *storage)
  * mcp_account_storage_description:
  * @storage: an #McpAccountStorage instance
  *
- * Returns: a const #gchar* : the plugin's description (for logging etc)
+ * Returns: the plugin's description (for logging etc)
  */
 const gchar *
 mcp_account_storage_description (const McpAccountStorage *storage)
@@ -719,8 +725,7 @@ mcp_account_storage_description (const McpAccountStorage *storage)
  * mcp_account_storage_provider:
  * @storage: an #McpAccountStorage instance
  *
- * Returns: a const #gchar* : the plugin's provider, a DBus namespaced name for
- * this plugin.
+ * Returns: a DBus namespaced name for this plugin.
  */
 const gchar *
 mcp_account_storage_provider (const McpAccountStorage *storage)
diff --git a/mission-control-plugins/account-storage.h b/mission-control-plugins/account-storage.h
index 50537653..056674b1 100644
--- a/mission-control-plugins/account-storage.h
+++ b/mission-control-plugins/account-storage.h
@@ -164,7 +164,7 @@ gboolean mcp_account_storage_set (const McpAccountStorage *storage,
     const McpAccountManager *am,
     const gchar *account,
     const gchar *key,
-    const gchar *val);
+    const gchar *value);
 
 gboolean mcp_account_storage_delete (const McpAccountStorage *storage,
     const McpAccountManager *am,
diff --git a/mission-control-plugins/dispatch-operation-policy.c b/mission-control-plugins/dispatch-operation-policy.c
index e31be47d..622364f5 100644
--- a/mission-control-plugins/dispatch-operation-policy.c
+++ b/mission-control-plugins/dispatch-operation-policy.c
@@ -241,6 +241,7 @@ mcp_dispatch_operation_policy_handler_is_suitable_async (
 }
 
 /**
+ * mcp_dispatch_operation_policy_handler_is_suitable_finish:
  * @policy: an implementation of this interface, provided by a plugin
  * @result: the asynchronous result passed to the #GAsyncReadyCallback
  * @error: (allow-none): used to return an error