[gnome-keyring] gcr: Documentation and naming fixes.

[Stefan Walter <stefw src gnome org>]

commit 2499a975104818217e83b1685ed390fcfb6661b5
Author: Stef Walter <stefw collabora co uk>
Date:   Sun May 15 06:53:53 2011 +0200

    gcr: Documentation and naming fixes.
    
     * Fixes after review.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=648019

 gcr/gcr-gnupg-collection.c |   45 +++++++++++++++++++-------------
 gcr/gcr-gnupg-key.c        |   61 +++++++++++++++++++++++++++++++------------
 2 files changed, 71 insertions(+), 35 deletions(-)
---
diff --git a/gcr/gcr-gnupg-collection.c b/gcr/gcr-gnupg-collection.c
index 3f82e24..454238b 100644
--- a/gcr/gcr-gnupg-collection.c
+++ b/gcr/gcr-gnupg-collection.c
@@ -37,13 +37,7 @@
 
 enum {
 	PROP_0,
-	PROP_DIRECTORY,
-	PROP_MAIN_CONTEXT
-};
-
-enum {
-	PHASE_PUBLIC_KEYS = 1,
-	PHASE_SECRET_KEYS = 2,
+	PROP_DIRECTORY
 };
 
 struct _GcrGnupgCollectionPrivate {
@@ -172,15 +166,14 @@ _gcr_collection_iface (GcrCollectionIface *iface)
 
 /**
  * _gcr_gnupg_collection_new:
- * @directory: The gnupg home directory, or %NULL
+ * @directory: (allow-none): The gnupg home directory.
  *
  * Create a new GcrGnupgCollection.
  *
  * The gnupg home directory is where the keyring files live. If directory is
  * %NULL then the default gnupg home directory is used.
  *
- * Returns: A newly allocated collection, which should be released with
- *     g_object_unref().
+ * Returns: (transfer full): A newly allocated collection.
  */
 GcrCollection*
 _gcr_gnupg_collection_new (const gchar *directory)
@@ -191,6 +184,22 @@ _gcr_gnupg_collection_new (const gchar *directory)
 }
 
 /*
+ * We have to run the gnupg process twice to list the public and then the
+ * secret keys. These phases are tracked by GcrLoadingPhase. If the first
+ * phase completes successfully (using gpg --list-keys) then we move on to
+ * the second phase where the secret keys are loaded (using gpg --list-secret-keys)
+ *
+ * If a key is loaded as a public key by the public phase, it can be updated by
+ * the secret phase. A key discovered in the secret phase must have a public
+ * counterpart already loaded by the public phase.
+ */
+
+typedef enum {
+	GCR_LOADING_PHASE_PUBLIC = 1,
+	GCR_LOADING_PHASE_SECRET = 2,
+} GcrLoadingPhase;
+
+/*
  * We use @difference to track the keys that were in the collection before
  * the load process, and then remove any not found, at the end of the load
  * process. Strings are directly used from collection->pv->items keys.
@@ -198,7 +207,7 @@ _gcr_gnupg_collection_new (const gchar *directory)
 
 typedef struct {
 	GcrGnupgCollection *collection;       /* reffed pointer back to collection */
-	gint loading_phase;
+	GcrLoadingPhase loading_phase;        /* Whether loading public or private */
 	GPtrArray *dataset;                   /* GcrColons* not yet made into a key */
 	guint spawn_sig;
 	guint child_sig;
@@ -267,7 +276,7 @@ process_dataset_as_secret_key (GcrGnupgCollectionLoad *load, GPtrArray *dataset,
 
 	/* Don't have this key */
 	if (key == NULL)
-		g_message ("secret key seen but no public key for: %s", keyid);
+		g_message ("Secret key seen but no public key for: %s", keyid);
 
 	/* Tell the private key that it's a secret one */
 	else
@@ -420,11 +429,11 @@ on_spawn_completed (gpointer user_data)
 
 	/* If we completed loading public keys, then go and load secret */
 	switch (load->loading_phase) {
-	case PHASE_PUBLIC_KEYS:
-		load->loading_phase = PHASE_SECRET_KEYS;
+	case GCR_LOADING_PHASE_PUBLIC:
+		load->loading_phase = GCR_LOADING_PHASE_SECRET;
 		spawn_gnupg_list_process (load, res);
 		return;
-	case PHASE_SECRET_KEYS:
+	case GCR_LOADING_PHASE_SECRET:
 		/* continue below */
 		break;
 	default:
@@ -489,10 +498,10 @@ spawn_gnupg_list_process (GcrGnupgCollectionLoad *load, GSimpleAsyncResult *res)
 	g_ptr_array_add (argv, (gpointer)GPG_EXECUTABLE);
 
 	switch (load->loading_phase) {
-	case PHASE_PUBLIC_KEYS:
+	case GCR_LOADING_PHASE_PUBLIC:
 		g_ptr_array_add (argv, (gpointer)"--list-keys");
 		break;
-	case PHASE_SECRET_KEYS:
+	case GCR_LOADING_PHASE_SECRET:
 		g_ptr_array_add (argv, (gpointer)"--list-secret-keys");
 		break;
 	default:
@@ -578,7 +587,7 @@ _gcr_gnupg_collection_load_async (GcrGnupgCollection *self, GCancellable *cancel
 	g_simple_async_result_set_op_res_gpointer (res, load,
 	                                           _gcr_gnupg_collection_load_free);
 
-	load->loading_phase = PHASE_PUBLIC_KEYS;
+	load->loading_phase = GCR_LOADING_PHASE_PUBLIC;
 	spawn_gnupg_list_process (load, res);
 
 	g_object_unref (res);
diff --git a/gcr/gcr-gnupg-key.c b/gcr/gcr-gnupg-key.c
index 2f078e2..a59523a 100644
--- a/gcr/gcr-gnupg-key.c
+++ b/gcr/gcr-gnupg-key.c
@@ -173,26 +173,57 @@ _gcr_gnupg_key_class_init (GcrGnupgKeyClass *klass)
 	gobject_class->set_property = _gcr_gnupg_key_set_property;
 	gobject_class->get_property = _gcr_gnupg_key_get_property;
 
+	/**
+	 * GcrGnupgKey::public-dataset:
+	 *
+	 * Public key data. Should always be present.
+	 */
 	g_object_class_install_property (gobject_class, PROP_PUBLIC_DATASET,
 	         g_param_spec_boxed ("public-dataset", "Public Dataset", "Public Key Colon Dataset",
 	                             G_TYPE_PTR_ARRAY, G_PARAM_READWRITE));
 
+	/**
+	 * GcrGnupgKey::secret-dataset:
+	 *
+	 * Secret key data. The keyid of this data must match public-dataset.
+	 * If present, this key represents a secret key.
+	 */
 	g_object_class_install_property (gobject_class, PROP_SECRET_DATASET,
 	         g_param_spec_boxed ("secret-dataset", "Secret Dataset", "Secret Key Colon Dataset",
 	                             G_TYPE_PTR_ARRAY, G_PARAM_READWRITE));
 
+	/**
+	 * GcrGnupgKey::label:
+	 *
+	 * User readable label for this key.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LABEL,
 	         g_param_spec_string ("label", "Label", "Key label",
 	                              "", G_PARAM_READABLE));
 
+	/**
+	 * GcrGnupgKey::description:
+	 *
+	 * Description of type of key.
+	 */
 	g_object_class_install_property (gobject_class, PROP_DESCRIPTION,
 	         g_param_spec_string ("description", "Description", "Description of object type",
 	                              "", G_PARAM_READABLE));
 
+	/**
+	 * GcrGnupgKey::markup:
+	 *
+	 * User readable markup which contains key label.
+	 */
 	g_object_class_install_property (gobject_class, PROP_MARKUP,
 	         g_param_spec_string ("markup", "Markup", "Markup which describes key",
 	                              "", G_PARAM_READABLE));
 
+	/**
+	 * GcrGnupgKey::keyid:
+	 *
+	 * User readable key identifier.
+	 */
 	g_object_class_install_property (gobject_class, PROP_KEYID,
 	         g_param_spec_string ("keyid", "Key ID", "Display key identifier",
 	                              "", G_PARAM_READABLE));
@@ -201,13 +232,13 @@ _gcr_gnupg_key_class_init (GcrGnupgKeyClass *klass)
 /**
  * _gcr_gnupg_key_new:
  * @pubset: array of GcrColons* representing public part of key
- * @secset: optional array of GcrColons* representing secret part of key.
+ * @secset: (allow-none): array of GcrColons* representing secret part of key.
  *
  * Create a new GcrGnupgKey for the colons data passed. If the secret part
- * of the key is set, then this represents a secret key.
+ * of the key is set, then this represents a secret key; otherwise it represents
+ * a public key.
  *
- * Returns: A newly allocated key, which should be released with
- *     g_object_unref().
+ * Returns: (transfer full): A newly allocated key.
  */
 GcrGnupgKey*
 _gcr_gnupg_key_new (GPtrArray *pubset, GPtrArray *secset)
@@ -225,7 +256,7 @@ _gcr_gnupg_key_new (GPtrArray *pubset, GPtrArray *secset)
  *
  * Get the colons data this key is based on.
  *
- * Returns: An array of GcrColons*, owned by the key.
+ * Returns: (transfer none): An array of GcrColons*.
  */
 GPtrArray*
 _gcr_gnupg_key_get_public_dataset (GcrGnupgKey *self)
@@ -245,16 +276,14 @@ void
 _gcr_gnupg_key_set_public_dataset (GcrGnupgKey *self, GPtrArray *dataset)
 {
 	GObject *obj;
-	const gchar *old_keyid;
-	const gchar *new_keyid;
 
 	g_return_if_fail (GCR_IS_GNUPG_KEY (self));
 	g_return_if_fail (dataset);
 
 	/* Check that it matches previous */
 	if (self->pv->public_dataset) {
-		old_keyid = _gcr_gnupg_key_get_keyid_for_colons (self->pv->public_dataset);
-		new_keyid = _gcr_gnupg_key_get_keyid_for_colons (dataset);
+		const gchar *old_keyid = _gcr_gnupg_key_get_keyid_for_colons (self->pv->public_dataset);
+		const gchar *new_keyid = _gcr_gnupg_key_get_keyid_for_colons (dataset);
 
 		if (g_strcmp0 (old_keyid, new_keyid) != 0) {
 			g_warning ("it is an error to change a gnupg key so that the "
@@ -283,7 +312,7 @@ _gcr_gnupg_key_set_public_dataset (GcrGnupgKey *self, GPtrArray *dataset)
  *
  * Get the colons secret data this key is based on. %NULL if a public key.
  *
- * Returns: An array of GcrColons*, owned by the key.
+ * Returns: (transfer none): An array of GcrColons*.
  */
 GPtrArray*
 _gcr_gnupg_key_get_secret_dataset (GcrGnupgKey *self)
@@ -295,7 +324,7 @@ _gcr_gnupg_key_get_secret_dataset (GcrGnupgKey *self)
 /**
  * _gcr_gnupg_key_set_secret_dataset:
  * @self: The key
- * @dataset: The new array of GcrColons*
+ * @dataset: (allow-none): The new array of GcrColons*
  *
  * Set the secret data for this key. %NULL if public key.
  */
@@ -303,15 +332,13 @@ void
 _gcr_gnupg_key_set_secret_dataset (GcrGnupgKey *self, GPtrArray *dataset)
 {
 	GObject *obj;
-	const gchar *pub_keyid;
-	const gchar *sec_keyid;
 
 	g_return_if_fail (GCR_IS_GNUPG_KEY (self));
 
 	/* Check that it matches public key */
 	if (self->pv->public_dataset && dataset) {
-		pub_keyid = _gcr_gnupg_key_get_keyid_for_colons (self->pv->public_dataset);
-		sec_keyid = _gcr_gnupg_key_get_keyid_for_colons (dataset);
+		const gchar *pub_keyid = _gcr_gnupg_key_get_keyid_for_colons (self->pv->public_dataset);
+		const gchar *sec_keyid = _gcr_gnupg_key_get_keyid_for_colons (dataset);
 
 		if (g_strcmp0 (pub_keyid, sec_keyid) != 0) {
 			g_warning ("it is an error to create a gnupg key so that the "
@@ -339,7 +366,7 @@ _gcr_gnupg_key_set_secret_dataset (GcrGnupgKey *self, GPtrArray *dataset)
  *
  * Get the keyid for some colons data.
  *
- * Returns: The keyid, owned by the colons data.
+ * Returns: (transfer none): The keyid.
  */
 const gchar*
 _gcr_gnupg_key_get_keyid_for_colons (GPtrArray *dataset)
@@ -360,7 +387,7 @@ _gcr_gnupg_key_get_keyid_for_colons (GPtrArray *dataset)
  *
  * Get the columns that we should display for gnupg keys.
  *
- * Returns: The columns, NULL terminated, should not be freed.
+ * Returns: (transfer none): The columns, NULL terminated, should not be freed.
  */
 const GcrColumn*
 _gcr_gnupg_key_get_columns (void)