[gnome-software] Add some more documentation about the different state and kind values

[Richard Hughes <rhughes src gnome org>]

commit e3d5fef532fc7161113a4433e67fedb613dbb33f
Author: Richard Hughes <richard hughsie com>
Date:   Tue Sep 10 09:47:51 2013 +0100

    Add some more documentation about the different state and kind values

 src/gs-app.c           |   17 +++++++++
 src/gs-plugin-loader.c |   93 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 110 insertions(+), 0 deletions(-)
---
diff --git a/src/gs-app.c b/src/gs-app.c
index 7978aa3..9b6f7ff 100644
--- a/src/gs-app.c
+++ b/src/gs-app.c
@@ -19,6 +19,23 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+/**
+ * SECTION:gs-app
+ * @short_description: An application that is either installed or that can be installed
+ *
+ * This object represents a 1:1 mapping to a .desktop file. The design is such
+ * so you can't have different GsApp's for different versions or arcitectures
+ * of a package.
+ *
+ * In the #GsPluginLoader the deduplication functionality uses the id to try
+ * and remove duplicate entries, so this should be the primary key for this
+ * object.
+ *
+ * Infrormation about other #GsApp objects can be stored in this object, for
+ * instance in the gs_app_add_related() method or the future method
+ * gs_app_get_history().
+ */
+
 #include "config.h"
 
 #include <string.h>
diff --git a/src/gs-plugin-loader.c b/src/gs-plugin-loader.c
index 06cda07..89ba021 100644
--- a/src/gs-plugin-loader.c
+++ b/src/gs-plugin-loader.c
@@ -507,6 +507,25 @@ out:
 
 /**
  * gs_plugin_loader_get_updates_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_updates()
+ * function. The plugins can either return #GsApp objects of kind
+ * %GS_APP_KIND_NORMAL for bonafide applications, or #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE for packages that may or may not be applications.
+ *
+ * Once the list of updates is refined, some of the #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE will have been promoted to a kind of %GS_APP_KIND_NORMAL,
+ * or if they are core applications, promoted again to a kind of %GS_APP_KIND_SYSTEM.
+ *
+ * Any #GsApp's of kind %GS_APP_KIND_PACKAGE that remain after refining are
+ * added to a new virtual #GsApp of kind %GS_APP_KIND_OS_UPDATE and all the
+ * %GS_APP_KIND_PACKAGE objects are moved to related packages of this object.
+ *
+ * This means all of the #GsApp's returning from this function are of kind
+ * %GS_APP_KIND_NORMAL, %GS_APP_KIND_SYSTEM or %GS_APP_KIND_OS_UPDATE.
+ *
+ * The #GsApps may be in state %GS_APP_STATE_INSTALLED or %GS_APP_STATE_AVAILABLE
+ * and the UI may want to filter the two classes of applications differently.
  **/
 void
 gs_plugin_loader_get_updates_async (GsPluginLoader *plugin_loader,
@@ -608,6 +627,23 @@ out:
 
 /**
  * gs_plugin_loader_get_installed_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_installed()
+ * function. The plugins can either return #GsApp objects of kind
+ * %GS_APP_KIND_NORMAL for bonafide applications, or #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE for packages that may or may not be applications.
+ *
+ * Once the list of updates is refined, some of the #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE will have been promoted to a kind of %GS_APP_KIND_NORMAL,
+ * or if they are core applications, promoted again to a kind of %GS_APP_KIND_SYSTEM.
+ *
+ * Any #GsApp's of kind %GS_APP_KIND_PACKAGE or %GS_APP_KIND_SYSTEM that remain
+ * after refining are automatically removed.
+ *
+ * This means all of the #GsApp's returning from this function are of kind
+ * %GS_APP_KIND_NORMAL.
+ *
+ * The #GsApps will all initially be in state %GS_APP_STATE_INSTALLED.
  **/
 void
 gs_plugin_loader_get_installed_async (GsPluginLoader *plugin_loader,
@@ -808,6 +844,24 @@ out:
 
 /**
  * gs_plugin_loader_get_featured_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_featured()
+ * function. The plugins can either return #GsApp objects of kind
+ * %GS_APP_KIND_NORMAL for bonafide applications, or #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE for packages that may or may not be applications.
+ *
+ * Once the list of updates is refined, some of the #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE will have been promoted to a kind of %GS_APP_KIND_NORMAL,
+ * or if they are core applications, promoted again to a kind of %GS_APP_KIND_SYSTEM.
+ *
+ * Any #GsApp's of kind %GS_APP_KIND_PACKAGE that remain after refining are
+ * automatically removed.
+ *
+ * This means all of the #GsApp's returning from this function are of kind
+ * %GS_APP_KIND_NORMAL or %GS_APP_KIND_SYSTEM.
+ *
+ * The #GsApps may be in state %GS_APP_STATE_INSTALLED or %GS_APP_STATE_AVAILABLE
+ * and the UI may want to filter the two classes of applications differently.
  **/
 void
 gs_plugin_loader_get_featured_async (GsPluginLoader *plugin_loader,
@@ -951,6 +1005,24 @@ out:
 
 /**
  * gs_plugin_loader_search_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_search()
+ * function. The plugins can either return #GsApp objects of kind
+ * %GS_APP_KIND_NORMAL for bonafide applications, or #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE for packages that may or may not be applications.
+ *
+ * Once the list of updates is refined, some of the #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE will have been promoted to a kind of %GS_APP_KIND_NORMAL,
+ * or if they are core applications, promoted again to a kind of %GS_APP_KIND_SYSTEM.
+ *
+ * Any #GsApp's of kind %GS_APP_KIND_PACKAGE or %GS_APP_KIND_SYSTEM that remain
+ * after refining are automatically removed.
+ *
+ * This means all of the #GsApp's returning from this function are of kind
+ * %GS_APP_KIND_NORMAL.
+ *
+ * The #GsApps may be in state %GS_APP_STATE_INSTALLED or %GS_APP_STATE_AVAILABLE
+ * and the UI may want to filter the two classes of applications differently.
  **/
 void
 gs_plugin_loader_search_async (GsPluginLoader *plugin_loader,
@@ -1096,6 +1168,9 @@ out:
 
 /**
  * gs_plugin_loader_get_categories_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_categories()
+ * function. The plugins return #GsCategory objects.
  **/
 void
 gs_plugin_loader_get_categories_async (GsPluginLoader *plugin_loader,
@@ -1243,6 +1318,24 @@ out:
 
 /**
  * gs_plugin_loader_get_category_apps_async:
+ *
+ * This method calls all plugins that implement the gs_plugin_add_category_apps()
+ * function. The plugins can either return #GsApp objects of kind
+ * %GS_APP_KIND_NORMAL for bonafide applications, or #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE for packages that may or may not be applications.
+ *
+ * Once the list of updates is refined, some of the #GsApp's of kind
+ * %GS_APP_KIND_PACKAGE will have been promoted to a kind of %GS_APP_KIND_NORMAL,
+ * or if they are core applications, promoted again to a kind of %GS_APP_KIND_SYSTEM.
+ *
+ * Any #GsApp's of kind %GS_APP_KIND_PACKAGE or %GS_APP_KIND_SYSTEM that remain
+ * after refining are automatically removed.
+ *
+ * This means all of the #GsApp's returning from this function are of kind
+ * %GS_APP_KIND_NORMAL.
+ *
+ * The #GsApps may be in state %GS_APP_STATE_INSTALLED or %GS_APP_STATE_AVAILABLE
+ * and the UI may want to filter the two classes of applications differently.
  **/
 void
 gs_plugin_loader_get_category_apps_async (GsPluginLoader *plugin_loader,