Add comments for outliner's treestore and treehash (no functional changes)

2 files changed, 19 insertions, 3 deletions

diff --git a/source/blender/editors/space_outliner/outliner_tree.c b/source/blender/editors/space_outliner/outliner_tree.c
index 404821900df..2a6320b83b1 100644
--- a/source/blender/editors/space_outliner/outliner_tree.c
+++ b/source/blender/editors/space_outliner/outliner_tree.c
@@ -151,7 +151,8 @@ static void outliner_storage_cleanup(SpaceOops *soops)
 }
 
 /* This function hashes only by type, nr and id, while cmp function also compares 'used' flag;
- * This is done to skip full treehash rebuild in outliner_storage_cleanup */
+ * This is done to skip full treehash rebuild in outliner_storage_cleanup;
+ * In general hashing by type, nr and id should be enough to distribute elements in buckets uniformly */
 static unsigned int tse_hash(const void *ptr)
 {
 	const TreeStoreElem *tse = (const TreeStoreElem *)ptr;
@@ -194,6 +195,8 @@ static void check_persistent(SpaceOops *soops, TreeElement *te, ID *id, short ty
 	}
 	if (soops->treehash == NULL) {
 		soops->treehash = BLI_ghash_new(tse_hash, tse_cmp, "treehash");
+		
+		/* treehash elements are not required to be unique; see soops->treehash comment */
 		BLI_ghash_flag_set(soops->treehash, GHASH_FLAG_ALLOW_DUPES);
 	}
 	
@@ -205,7 +208,8 @@ static void check_persistent(SpaceOops *soops, TreeElement *te, ID *id, short ty
 		}
 	}
 
-	/* check for unused tree elements is in treestore */
+	/* find any unused tree element in treestore and mark it as used
+	 * (note that there may be multiple unused elements in case of linked objects) */
 	tselem = lookup_treehash(soops->treehash, type, nr, 0, id);
 	if (tselem) {
 		te->store_elem = tselem;
diff --git a/source/blender/makesdna/DNA_space_types.h b/source/blender/makesdna/DNA_space_types.h
index 85655ce09bd..3e1196fb45a 100644
--- a/source/blender/makesdna/DNA_space_types.h
+++ b/source/blender/makesdna/DNA_space_types.h
@@ -246,6 +246,13 @@ typedef struct SpaceOops {
 	View2D v2d DNA_DEPRECATED;  /* deprecated, copied to region */
 	
 	ListBase tree;
+	
+	/* treestore is an ordered list of TreeStoreElem's from outliner tree;
+	 * Note that treestore may contain duplicate elements if element
+	 * is used multiple times in outliner tree (e. g. linked objects)
+	 * Also note that BLI_mempool can not be read/written in DNA directly,
+	 * therefore readfile.c/writefile.c linearize treestore into TreeStore structure
+	 */
 	struct BLI_mempool *treestore;
 	
 	/* search stuff */
@@ -253,7 +260,12 @@ typedef struct SpaceOops {
 	struct TreeStoreElem search_tse;
 
 	short flag, outlinevis, storeflag, search_flags;
-	struct GHash *treehash;  /* note, allows duplicates */
+	
+	/* search index for every element in treestore;
+	 * It is ok for treehash to contain duplicates, because the semantics of its usage
+	 * allows duplicates (see check_persistent)
+	 */
+	struct GHash *treehash;
 } SpaceOops;