[gtk+/filesystemmodel] Comment on how the file_lookup hash table gets rebuilt on demand

[Federico Mena Quintero <federico src gnome org>]

commit c68c0e5a1c6a05753e169b1ddd5aece9631bf563
Author: Federico Mena Quintero <federico novell com>
Date:   Wed Sep 2 14:51:02 2009 -0500

    Comment on how the file_lookup hash table gets rebuilt on demand
    
    Signed-off-by: Federico Mena Quintero <federico novell com>

 gtk/gtkfilesystemmodel.c |   17 +++++++++++++++--
 1 files changed, 15 insertions(+), 2 deletions(-)
---
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index 509a361..69cd059 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -72,7 +72,12 @@ struct _GtkFileSystemModel
   GArray *              files;          /* array of FileModelNode containing all our files */
   GSize                 node_size;	/* Size of a FileModelNode structure once its ->values field has n_columns */
   guint                 n_indexes_valid;/* count of valid indexes */
-  GHashTable *          file_lookup;    /* file => array index table */
+  GHashTable *          file_lookup;    /* file => array index table.
+					 * This hash table doesn't always have the same number of entries as the files array;
+					 * it can get cleared completely when we resort.
+					 * The hash table gets re-populated in node_get_for_file() if this mismatch is
+					 * detected.
+					 */
 
   guint                 n_columns;      /* number of columns */
   GType *               column_types;   /* types of each column */
@@ -1490,7 +1495,15 @@ node_get_for_file (GtkFileSystemModel *model,
   if (i != 0)
     return i;
 
-  /* node 0 is the editable row and has no associated file or entry in the table */
+  /* Node 0 is the editable row and has no associated file or entry in the table, so we start counting from 1.
+   *
+   * The invariant here is that the files in model->files[n] for n < g_hash_table_size (model->file_lookup)
+   * are already added to the hash table. The table can get cleared when we re-sort; this loop merely rebuilds
+   * our (file -> index) mapping on demand.
+   *
+   * If we exit the loop, the next pending batch of mappings will be resolved when this function gets called again
+   * with another file that is not yet in the mapping.
+   */
   for (i = g_hash_table_size (model->file_lookup) + 1; i < model->files->len; i++)
     {
       FileModelNode *node = get_node (model, i);