[gnome-software] Expand docs a bit

[Matthias Clasen <matthiasc src gnome org>]

commit e5dcafefbb633b554bb3e1dc8075da9ee650cf20
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Sep 10 07:34:01 2013 -0400

    Expand docs a bit

 src/gs-app.c |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)
---
diff --git a/src/gs-app.c b/src/gs-app.c
index 1b51975..c4aeaad 100644
--- a/src/gs-app.c
+++ b/src/gs-app.c
@@ -24,14 +24,19 @@
  * @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.
+ * so you can't have different GsApp's for different versions or architectures
+ * of a package. This rule really only applies to GsApps of kind GS_APP_KIND_NORMAL
+ * and GS_APP_KIND_SYSTEM. We allow GsApps of kind GS_APP_KIND_SYSTEM_UPDATE or
+ * GS_APP_KIND_PACKAGE, which don't correspond to desktop files, but instead
+ * represent a system update and its individual components.
  *
- * 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.
+ * The #GsPluginLoader de-duplicates the GsApp instances that are produced by
+ * plugins to ensure that there is a single instance of GsApp for each id, making
+ * the id the primary key for this object. This ensures that actions triggered on
+ * a GsApp in different parts of gnome-software can be observed by connecting to
+ * signals on the GsApp.
  *
- * Infrormation about other #GsApp objects can be stored in this object, for
+ * Information 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().
  */
@@ -233,7 +238,11 @@ gs_app_get_state (GsApp *app)
  * gs_app_set_state:
  *
  * This sets the state of the application. The following state diagram explains
- * the typical states. All applications start in state %GS_APP_STATE_UNKNOWN.
+ * the typical states. All applications start in state %GS_APP_STATE_UNKNOWN,
+ * but the frontend is not supposed to see GsApps with this state, ever.
+ * Backend plugins are reponsible for changing the state to one of the other
+ * states before the GsApp is passed to the frontend. This is enforced by the
+ * #GsPluginLoader.
  *
  * UPDATABLE --> INSTALLING --> INSTALLED
  * UPDATABLE --> REMOVING   --> AVAILABLE