Style cleanup, plus added comments on memory management

1 files changed, 25 insertions, 6 deletions

diff --git a/generic/tclStrIdxTree.h b/generic/tclStrIdxTree.h
index 28e0710..c5a6716 100644
--- a/generic/tclStrIdxTree.h
+++ b/generic/tclStrIdxTree.h
@@ -13,17 +13,36 @@
 #ifndef _TCLSTRIDXTREE_H
 #define _TCLSTRIDXTREE_H
 
+#include "tclInt.h"
+
 /*
  * Main structures declarations of index tree and entry
  */
 
 typedef struct TclStrIdx TclStrIdx;
 
+/*
+ * Top level structure of the tree, or first two fields of the interior
+ * structure.
+ * 
+ * Note that this is EXACTLY two pointers so it is the same size as the
+ * twoPtrValue of a Tcl_ObjInternalRep. This is how the top level structure
+ * of the tree is always allocated. (This type constraint is asserted in
+ * TclStrIdxTreeNewObj() so it's guaranteed.)
+ *
+ * Also note that if firstPtr is not NULL, lastPtr must also be not NULL.
+ * The case where firstPtr is not NULL and lastPtr is NULL is special (a
+ * smart pointer to one of these) and is not actually a valid instance of
+ * this structure.
+ */
 typedef struct TclStrIdxTree {
     TclStrIdx *firstPtr;
     TclStrIdx *lastPtr;
 } TclStrIdxTree;
 
+/*
+ * An interior node of the tree. Always directly allocated.
+ */
 struct TclStrIdx {
     TclStrIdxTree childTree;
     TclStrIdx *nextPtr;
@@ -38,13 +57,13 @@ struct TclStrIdx {
  *
  * TclUtfFindEqual, TclUtfFindEqualNC --
  *
- *  Find largest part of string cs in string cin (case sensitive and not).
+ *	Find largest part of string cs in string cin (case sensitive and not).
  *
  * Results:
- *  Return position of UTF character in cs after last equal character.
+ *	Return position of UTF character in cs after last equal character.
  *
  * Side effects:
- *  None.
+ *	None.
  *
  *----------------------------------------------------------------------
  */
@@ -133,14 +152,14 @@ TclUtfFindEqualNCInLwr(
     } while (0)
 #define TclInitObjRef(obj, val) \
     do {								\
-	obj = val;							\
+	obj = (val);							\
 	if (obj) {							\
 	    Tcl_IncrRefCount(obj);					\
 	}								\
     } while (0)
 #define TclSetObjRef(obj, val) \
     do {								\
-	Tcl_Obj *nval = val;						\
+	Tcl_Obj *nval = (val);						\
 	if (obj != nval) {						\
 	    Tcl_Obj *prev = obj;					\
 	    TclInitObjRef(obj, nval);					\
@@ -162,7 +181,7 @@ MODULE_SCOPE int	TclStrIdxTreeBuildFromList(TclStrIdxTree *idxTree,
 MODULE_SCOPE Tcl_Obj *	TclStrIdxTreeNewObj();
 MODULE_SCOPE TclStrIdxTree*TclStrIdxTreeGetFromObj(Tcl_Obj *objPtr);
 
-#if 0
+#ifdef TEST_STR_IDX_TREE
 /* currently unused, debug resp. test purposes only */
 MODULE_SCOPE Tcl_ObjCmdProc TclStrIdxTreeTestObjCmd;
 #endif