[gnome-software] trivial: Add some more gtk-doc based on questions on IRC

[Richard Hughes <rhughes src gnome org>]

commit 0a9dd1a27679f1eccef73535e7cfdd663e0b006b
Author: Richard Hughes <richard hughsie com>
Date:   Fri May 20 11:12:21 2016 +0100

    trivial: Add some more gtk-doc based on questions on IRC

 src/gs-app.c    |   13 ++++++++++++-
 src/gs-plugin.h |   33 +++++++++++++++++++++++++++++++--
 2 files changed, 43 insertions(+), 3 deletions(-)
---
diff --git a/src/gs-app.c b/src/gs-app.c
index 74cf8fa..32b8494 100644
--- a/src/gs-app.c
+++ b/src/gs-app.c
@@ -2868,10 +2868,21 @@ gs_app_init (GsApp *app)
 
 /**
  * gs_app_new:
- * @id: an ID, or %NULL
+ * @id: an application ID, or %NULL, e.g. "flatpak:org.gnome.Software.desktop"
  *
  * Creates a new application object.
  *
+ * The ID should only be set when the application ID (with optional prefix) is
+ * known; it is perfectly valid to use gs_app_new() with an @id of %NULL, and
+ * then relying on another plugin to set the @id using gs_app_set_id() based on
+ * some other information.
+ *
+ * For instance, a #GsApp is created with no ID when returning results from the
+ * packagekit plugin, but with the default source name set as the package name.
+ * The source name is read by the appstream plugin, and if matched in the
+ * AppStream XML the correct ID is set, along with other higher quality data
+ * like the application icon and long description.
+ *
  * Returns: a new #GsApp
  **/
 GsApp *
diff --git a/src/gs-plugin.h b/src/gs-plugin.h
index 3ca81fa..99922a8 100644
--- a/src/gs-plugin.h
+++ b/src/gs-plugin.h
@@ -546,7 +546,15 @@ gboolean    gs_plugin_add_category_apps            (GsPlugin       *plugin,
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
  *
- * Get popular applications.
+ * Get popular applications that should be featured on the main page as
+ * "Editors Picks".
+ * This is expected to be a curated list of applications that are high quality
+ * and feature-complete.
+ *
+ * The returned list of popular applications are not sorted, but each #GsApp has
+ * to be valid, for instance having a known state and a valid icon.
+ * If an insufficient number of applications are added by plugins then the
+ * section on the overview shell may be hidden.
  *
  * Plugins are expected to add new apps using gs_app_list_add().
  *
@@ -564,7 +572,16 @@ gboolean    gs_plugin_add_popular                  (GsPlugin       *plugin,
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError, or %NULL
  *
- * Get applications that should be featured.
+ * Get applications that should be featured as a large full-width banner on the
+ * overview page.
+ * This is expected to be a curated list of applications that are high quality
+ * and feature-complete.
+ *
+ * The returned list of popular applications are randomized in a way so that
+ * the same application is featured for the entire calendar day.
+ *
+ * NOTE: The UI code may expect that applications have additional metadata set on
+ * results, for instance <code>GnomeSoftware::FeatureTile-css</code>.
  *
  * Plugins are expected to add new apps using gs_app_list_add().
  *
@@ -732,6 +749,10 @@ gboolean    gs_plugin_update_cancel                (GsPlugin       *plugin,
  * gs_plugin_progress_update() if they will take more than tens of milliseconds
  * to complete.
  *
+ * On failure the error message returned will usually only be shown on the
+ * console, but it may also be retained on the #GsApp object.
+ * The UI code can retrieve the error using gs_app_get_last_error().
+ *
  * NOTE: Once the action is complete, the plugin must set the new state of @app
  * to %AS_APP_STATE_INSTALLED.
  *
@@ -758,6 +779,10 @@ gboolean    gs_plugin_app_install                  (GsPlugin       *plugin,
  * gs_plugin_progress_update() if they will take more than tens of milliseconds
  * to complete.
  *
+ * On failure the error message returned will usually only be shown on the
+ * console, but it may also be retained on the #GsApp object.
+ * The UI code can retrieve the error using gs_app_get_last_error().
+ *
  * NOTE: Once the action is complete, the plugin must set the new state of @app
  * to %AS_APP_STATE_AVAILABLE or %AS_APP_STATE_UNKNOWN if not known.
  *
@@ -802,6 +827,10 @@ gboolean    gs_plugin_app_set_rating               (GsPlugin       *plugin,
  * gs_plugin_progress_update() if they will take more than tens of milliseconds
  * to complete.
  *
+ * On failure the error message returned will usually only be shown on the
+ * console, but it may also be retained on the #GsApp object.
+ * The UI code can retrieve the error using gs_app_get_last_error().
+ *
  * NOTE: Once the action is complete, the plugin must set the new state of @app
  * to %AS_APP_STATE_INSTALLED or %AS_APP_STATE_UNKNOWN if not known.
  *