[gnome-keyring] gcr: Add more comments for new colons and collection code.

[Stefan Walter <stefw src gnome org>]

commit 17f8d347b84c58df39c4b1a1dcc71154861d931d
Author: Stef Walter <stefw collabora co uk>
Date:   Mon Apr 18 22:47:19 2011 +0200

    gcr: Add more comments for new colons and collection code.

 gcr/gcr-colons.c           |    1 +
 gcr/gcr-colons.h           |   27 +++++++++++++++++++++++++++
 gcr/gcr-gnupg-collection.c |   14 ++++++++++++++
 gcr/gcr-util.c             |    6 ++++++
 4 files changed, 48 insertions(+), 0 deletions(-)
---
diff --git a/gcr/gcr-colons.c b/gcr/gcr-colons.c
index 4a54934..6a5d6be 100644
--- a/gcr/gcr-colons.c
+++ b/gcr/gcr-colons.c
@@ -100,6 +100,7 @@ _gcr_colons_get_string (GcrColons *colons, guint column)
 	if (g_utf8_validate (text, -1, NULL))
 		return text;
 
+	/* If it's not UTF-8, we guess that it's latin1 */
 	converted = g_convert (text, -1, "UTF-8", "ISO-8859-1", NULL, NULL, NULL);
 	g_free (text);
 
diff --git a/gcr/gcr-colons.h b/gcr/gcr-colons.h
index b8a055e..565df0a 100644
--- a/gcr/gcr-colons.h
+++ b/gcr/gcr-colons.h
@@ -30,19 +30,46 @@
 
 #include <glib.h>
 
+/*
+ * Gnupg's official format for listing keys is in the '--with-colons' format.
+ * This is documented in doc/DETAILS in the gnupg distribution. Looks like:
+ *
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ * fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
+ * uid:f::::::::Werner Koch <wk g10code com>:
+ * uid:f::::::::Werner Koch <wk gnupg org>:
+ * sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
+ * fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
+ * sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
+ * fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
+ *
+ * Each row is colon delimeted, and has a certain 'schema'. The first item
+ * in the row tells us the schema. Then the various columns are numbered,
+ * (schema is zero).
+ */
+
 G_BEGIN_DECLS
 
 #define GCR_COLONS_SCHEMA_UID  _gcr_colons_get_schema_uid_quark ()
 #define GCR_COLONS_SCHEMA_PUB  _gcr_colons_get_schema_pub_quark ()
 
+/* Common columns for all schemas */
 typedef enum {
 	GCR_COLONS_SCHEMA = 0
 } GcrColonColumns;
 
+/*
+ * Columns for pub schema, add them as they're used. eg:
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ */
 typedef enum {
 	GCR_COLONS_PUB_KEYID = 4
 } GcrColonPubColumns;
 
+/*
+ * Columns for uid schema, add them as they're used. eg:
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ */
 typedef enum {
 	GCR_COLONS_UID_NAME = 9
 } GcrColonUidColumns;
diff --git a/gcr/gcr-gnupg-collection.c b/gcr/gcr-gnupg-collection.c
index 812a35f..97f5840 100644
--- a/gcr/gcr-gnupg-collection.c
+++ b/gcr/gcr-gnupg-collection.c
@@ -256,12 +256,21 @@ on_line_parse_output (const gchar *line, gpointer user_data)
 	}
 
 	schema = _gcr_colons_get_schema (colons);
+
+	/*
+	 * Each time we see a line with 'pub' schema we assume that it's
+	 * a new key being listed.
+	 */
 	if (schema == GCR_COLONS_SCHEMA_PUB) {
 		if (load->dataset->len)
 			process_dataset_as_key (load);
 		g_assert (!load->dataset->len);
 		g_ptr_array_add (load->dataset, colons);
 		colons = NULL;
+
+	/*
+	 * 'uid' schema lines get added to the key that came before.
+	 */
 	} else if (schema == GCR_COLONS_SCHEMA_UID) {
 		if (load->dataset->len) {
 			g_ptr_array_add (load->dataset, colons);
@@ -435,6 +444,11 @@ _gcr_gnupg_collection_load_async (GcrGnupgCollection *self, GCancellable *cancel
 	load->out_data = g_string_sized_new (1024);
 	load->difference = g_hash_table_new (g_str_hash, g_str_equal);
 	load->collection = g_object_ref (self);
+
+	/*
+	 * Track all the keys we currently have, at end remove those that
+	 * didn't get listed by the gpg process.
+	 */
 	g_hash_table_foreach (self->pv->items, on_each_item_add_keyid_to_difference,
 	                      load->difference);
 
diff --git a/gcr/gcr-util.c b/gcr/gcr-util.c
index 3929d5b..739d0c7 100644
--- a/gcr/gcr-util.c
+++ b/gcr/gcr-util.c
@@ -27,6 +27,12 @@
 
 #include <string.h>
 
+/*
+ * Calls callback for each line. If last_line, also sends the remainder
+ * data that comes after the last line break. \n and \r\n are line separators.
+ * Neither are sent.
+ */
+
 void
 _gcr_util_parse_lines (GString *string, gboolean last_line,
                        GcrLineCallback callback, gpointer user_data)