Comment formatting improvements.

FossilOrigin-Name: 04b750c442d33c5c0e907c4de29a21e789b2ba37

1 files changed, 113 insertions, 102 deletions

diff --git a/generic/tclInt.h b/generic/tclInt.h
index 7551956..67ba634 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -15,14 +15,14 @@
  * See the file "license.terms" for information on usage and redistribution of
  * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclInt.h,v 1.411 2009/01/05 09:48:11 dkf Exp $
+ * RCS: @(#) $Id: tclInt.h,v 1.412 2009/01/06 09:49:39 dkf Exp $
  */
 
 #ifndef _TCLINT
 #define _TCLINT
 
 /*
- * Some numerics configuration options
+ * Some numerics configuration options.
  */
 
 #undef NO_WIDE_TYPE
@@ -274,9 +274,9 @@ typedef struct Namespace {
 				 * is currently allocated. */
     int cmdRefEpoch;		/* Incremented if a newly added command
 				 * shadows a command for which this namespace
-				 * has already cached a Command * pointer;
-				 * this causes all its cached Command*
-				 * pointers to be invalidated. */
+				 * has already cached a Command* pointer; this
+				 * causes all its cached Command* pointers to
+				 * be invalidated. */
     int resolverEpoch;		/* Incremented whenever (a) the name
 				 * resolution rules change for this namespace
 				 * or (b) a newly added command shadows a
@@ -654,7 +654,7 @@ typedef struct VarInHash {
 #define VAR_ALL_HASH \
 	(VAR_IN_HASHTABLE|VAR_DEAD_HASH|VAR_NAMESPACE_VAR|VAR_ARRAY_ELEMENT)
 
-/* Trace and search state */
+/* Trace and search state. */
 
 #define VAR_TRACED_READ		0x10	/* TCL_TRACE_READS */
 #define VAR_TRACED_WRITE	0x20	/* TCL_TRACE_WRITES */
@@ -665,7 +665,7 @@ typedef struct VarInHash {
 #define VAR_ALL_TRACES \
 	(VAR_TRACED_READ|VAR_TRACED_WRITE|VAR_TRACED_ARRAY|VAR_TRACED_UNSET)
 
-/* Special handling on initialisation (only CompiledLocal) */
+/* Special handling on initialisation (only CompiledLocal). */
 #define VAR_ARGUMENT		0x100	/* KEEP OLD VALUE! See tclProc.c */
 #define VAR_TEMPORARY		0x200	/* KEEP OLD VALUE! See tclProc.c */
 #define VAR_IS_ARGS		0x400
@@ -781,7 +781,7 @@ typedef struct VarInHash {
     ((VarInHash *) (varPtr))->refCount
 
 /*
- * Macros for direct variable access by TEBC
+ * Macros for direct variable access by TEBC.
  */
 
 #define TclIsVarDirectReadable(varPtr) \
@@ -919,9 +919,9 @@ typedef struct Trace {
     ClientData clientData;	/* Arbitrary value to pass to proc. */
     struct Trace *nextPtr;	/* Next in list of traces for this interp. */
     int flags;			/* Flags governing the trace - see
-				 * Tcl_CreateObjTrace for details */
+				 * Tcl_CreateObjTrace for details. */
     Tcl_CmdObjTraceDeleteProc *delProc;
-				/* Procedure to call when trace is deleted */
+				/* Procedure to call when trace is deleted. */
 } Trace;
 
 /*
@@ -1093,15 +1093,15 @@ typedef struct CmdFrame {
      */
 
     int type;			/* Values see below. */
-    int level;			/* #Frames in stack, prevent O(n) scan of
-				 * list. */
-    int numLevels;		/* value of interp's numLevels when the frame
-				 * was pushed */
+    int level;			/* Number of frames in stack, prevent O(n)
+				 * scan of list. */
+    int numLevels;		/* Value of interp's numLevels when the frame
+				 * was pushed. */
     int *line;			/* Lines the words of the command start on. */
     int nline;
     CallFrame *framePtr;	/* Procedure activation record, may be
 				 * NULL. */
-    struct CmdFrame *nextPtr;	/* Link to calling frame */
+    struct CmdFrame *nextPtr;	/* Link to calling frame. */
 
     /*
      * Data needed for Eval vs TEBC
@@ -1139,27 +1139,28 @@ typedef struct CmdFrame {
 				 * in. */
 	} eval;
 	struct {
-	    const void *codePtr;/* Byte code currently executed */
-	    const char *pc;	/* and instruction pointer. */
+	    const void *codePtr;/* Byte code currently executed... */
+	    const char *pc;	/* ... and instruction pointer. */
 	} tebc;
     } data;
     union {
 	struct {
-	    const char *cmd;	/* The executed command, if possible */
-	    int len;		/* And its length */
+	    const char *cmd;	/* The executed command, if possible... */
+	    int len;		/* ... and its length. */
 	} str;
-	Tcl_Obj *listPtr;	/* Tcl_EvalObjEx, cmd list */
+	Tcl_Obj *listPtr;	/* Tcl_EvalObjEx, cmd list. */
     } cmd;
 } CmdFrame;
 
 typedef struct CFWord {
-    CmdFrame *framePtr;		/* CmdFrame to acess */
-    int word;			/* Index of the word in the command */
-    int refCount;		/* #times the word is on the stack */
+    CmdFrame *framePtr;		/* CmdFrame to access. */
+    int word;			/* Index of the word in the command. */
+    int refCount;		/* Number of times the word is on the
+				 * stack. */
 } CFWord;
 
 typedef struct ExtIndex {
-    Tcl_Obj *obj;		/* Reference to the word */
+    Tcl_Obj *obj;		/* Reference to the word. */
     int pc;			/* Instruction pointer of a command in
 				 * ExtCmdLoc.loc[.] */
     int word;			/* Index of word in
@@ -1167,9 +1168,10 @@ typedef struct ExtIndex {
 } ExtIndex;
 
 typedef struct CFWordBC {
-    CmdFrame *framePtr;		/* CmdFrame to acess */
-    ExtIndex *eiPtr;		/* Word info: PC and index */
-    int refCount;		/* #times the word is on the stack */
+    CmdFrame *framePtr;		/* CmdFrame to access. */
+    ExtIndex *eiPtr;		/* Word info: PC and index. */
+    int refCount;		/* Number of times the word is on the
+				 * stack. */
 } CFWordBC;
 
 /*
@@ -1190,15 +1192,15 @@ typedef struct CFWordBC {
  * types, per the context of the byte code in execution.
  */
 
-#define TCL_LOCATION_EVAL	(0) /* Location in a dynamic eval script */
+#define TCL_LOCATION_EVAL	(0) /* Location in a dynamic eval script. */
 #define TCL_LOCATION_EVAL_LIST	(1) /* Location in a dynamic eval script,
-				     * list-path */
-#define TCL_LOCATION_BC		(2) /* Location in byte code */
+				     * list-path. */
+#define TCL_LOCATION_BC		(2) /* Location in byte code. */
 #define TCL_LOCATION_PREBC	(3) /* Location in precompiled byte code, no
-				     * location */
-#define TCL_LOCATION_SOURCE	(4) /* Location in a file */
-#define TCL_LOCATION_PROC	(5) /* Location in a dynamic proc */
-#define TCL_LOCATION_LAST	(6) /* Number of values in the enum */
+				     * location. */
+#define TCL_LOCATION_SOURCE	(4) /* Location in a file. */
+#define TCL_LOCATION_PROC	(5) /* Location in a dynamic proc. */
+#define TCL_LOCATION_LAST	(6) /* Number of values in the enum. */
 
 /*
  * Structure passed to describe procedure-like "procedures" that are not
@@ -1335,16 +1337,21 @@ typedef struct CorContext {
 } CorContext;
 
 typedef struct CoroutineData {
-    struct Command *cmdPtr;
-    struct ExecEnv *eePtr;
-    struct ExecEnv *callerEEPtr;
+    struct Command *cmdPtr;	/* The command handle for the coroutine. */
+    struct ExecEnv *eePtr;	/* The special execution environment (stacks,
+				 * etc.) for the coroutine. */
+    struct ExecEnv *callerEEPtr;/* The execution environment for the caller of
+				 * the coroutine, which might be the
+				 * interpreter global environment or another
+				 * coroutine. */
     CorContext caller;
     CorContext running;
     CorContext base;
     int *stackLevel;
-    int auxNumLevels;  /* While the coroutine is running the numLevels of the
-			* create/resume command is stored here; for suspended
-			* coroutines it holds the nesting numLevels at yield*/
+    int auxNumLevels;		/* While the coroutine is running the
+				 * numLevels of the create/resume command is
+				 * stored here; for suspended coroutines it
+				 * holds the nesting numLevels at yield. */
 } CoroutineData;
 
 typedef struct ExecEnv {
@@ -1353,7 +1360,7 @@ typedef struct ExecEnv {
     Tcl_Obj *constants[2];	/* Pointers to constant "0" and "1" objs. */
     struct Tcl_Interp *interp;
     struct TEOV_callback *callbackPtr;
-				/* Top callback in TEOV's stack */
+				/* Top callback in TEOV's stack. */
     struct CoroutineData *corPtr;
     struct BottomData *bottomPtr;
     int rewind;
@@ -1451,15 +1458,16 @@ typedef struct ByteCodeStats {
 
 /*
  * Structure used in implementation of those core ensembles which are
- * partially compiled.
+ * partially compiled. Used as an array of these, with a terminating field
+ * whose 'name' is NULL.
  */
 
 typedef struct {
-    const char        *name;        /* The name of the subcommand           */
-    Tcl_ObjCmdProc    *proc;        /* The implementation of the subcommand */
-    CompileProc       *compileProc; /* The compiler for the subcommand      */
-    Tcl_ObjCmdProc    *nreProc;     /* NRE implementation of this command   */
-    ClientData         clientData;  /* Any clientData to give the command   */
+    const char *name;		/* The name of the subcommand. */
+    Tcl_ObjCmdProc *proc;	/* The implementation of the subcommand. */
+    CompileProc *compileProc;	/* The compiler for the subcommand. */
+    Tcl_ObjCmdProc *nreProc;	/* NRE implementation of this command. */
+    ClientData clientData;	/* Any clientData to give the command. */
 } EnsembleImplMap;
 
 /*
@@ -1552,7 +1560,7 @@ typedef struct Command {
 				 * command. */
     CommandTrace *tracePtr;	/* First in list of all traces set for this
 				 * command. */
-    Tcl_ObjCmdProc *nreProc;    /* NRE implementation of this command */
+    Tcl_ObjCmdProc *nreProc;	/* NRE implementation of this command. */
 } Command;
 
 /*
@@ -1638,10 +1646,10 @@ enum PkgPreferOptions {
  */
 
 typedef struct AllocCache {
-    struct Cache *nextPtr;	/* Linked list of cache entries */
+    struct Cache *nextPtr;	/* Linked list of cache entries. */
     Tcl_ThreadId owner;		/* Which thread's cache is this? */
-    Tcl_Obj *firstObjPtr;	/* List of free objects for thread */
-    int numObjects;		/* Number of objects for thread */
+    Tcl_Obj *firstObjPtr;	/* List of free objects for thread. */
+    int numObjects;		/* Number of objects for thread. */
 } AllocCache;
 
 /*
@@ -1726,10 +1734,11 @@ typedef struct Interp {
     ActiveVarTrace *activeVarTracePtr;
 				/* First in list of active traces for interp,
 				 * or NULL if no active traces. */
-    int returnCode;		/* [return -code] parameter */
-    CallFrame *rootFramePtr;	/* Global frame pointer for this interpreter */
+    int returnCode;		/* [return -code] parameter. */
+    CallFrame *rootFramePtr;	/* Global frame pointer for this
+				 * interpreter. */
     Namespace *lookupNsPtr;	/* Namespace to use ONLY on the next
-				 * TCL_EVAL_INVOKE call to Tcl_EvalObjv */
+				 * TCL_EVAL_INVOKE call to Tcl_EvalObjv. */
 
     /*
      * Information used by Tcl_AppendResult to keep track of partial results.
@@ -1809,7 +1818,7 @@ typedef struct Interp {
     Tcl_Obj *objResultPtr;	/* If the last command returned an object
 				 * result, this points to it. Should not be
 				 * accessed directly; see comment above. */
-    Tcl_ThreadId threadId;	/* ID of thread that owns the interpreter */
+    Tcl_ThreadId threadId;	/* ID of thread that owns the interpreter. */
 
     ActiveCommandTrace *activeCmdTracePtr;
 				/* First in list of active command traces for
@@ -1818,19 +1827,22 @@ typedef struct Interp {
 				/* First in list of active traces for interp,
 				 * or NULL if no active traces. */
 
-    int tracesForbiddingInline; /* Count of traces (in the list headed by
+    int tracesForbiddingInline;	/* Count of traces (in the list headed by
 				 * tracePtr) that forbid inline bytecode
-				 * compilation */
+				 * compilation. */
+
+    /*
+     * Fields used to manage extensible return options (TIP 90).
+     */
 
-    /* Fields used to manage extensible return options (TIP 90) */
     Tcl_Obj *returnOpts;	/* A dictionary holding the options to the
-				 * last [return] command */
+				 * last [return] command. */
 
-    Tcl_Obj *errorInfo;		/* errorInfo value (now as a Tcl_Obj) */
-    Tcl_Obj *eiVar;		/* cached ref to ::errorInfo variable */
-    Tcl_Obj *errorCode;		/* errorCode value (now as a Tcl_Obj) */
-    Tcl_Obj *ecVar;		/* cached ref to ::errorInfo variable */
-    int returnLevel;		/* [return -level] parameter */
+    Tcl_Obj *errorInfo;		/* errorInfo value (now as a Tcl_Obj). */
+    Tcl_Obj *eiVar;		/* cached ref to ::errorInfo variable. */
+    Tcl_Obj *errorCode;		/* errorCode value (now as a Tcl_Obj). */
+    Tcl_Obj *ecVar;		/* cached ref to ::errorInfo variable. */
+    int returnLevel;		/* [return -level] parameter. */
 
     /*
      * Resource limiting framework support (TIP#143).
@@ -1888,7 +1900,7 @@ typedef struct Interp {
     } ensembleRewrite;
 
     /*
-     * TIP #219 ... Global info for the I/O system ...
+     * TIP #219: Global info for the I/O system.
      */
 
     Tcl_Obj *chanMsg;		/* Error message set by channel drivers, for
@@ -1910,7 +1922,10 @@ typedef struct Interp {
 				 * over the default error messages returned by
 				 * a script cancellation operation. */
 
-    /* TIP #280 */
+    /*
+     * Source code origin information (TIP #280).
+     */
+
     CmdFrame *cmdFramePtr;	/* Points to the command frame containing the
 				 * location information for the current
 				 * command. */
@@ -1954,13 +1969,13 @@ typedef struct Interp {
     int packagePrefer;		/* Current package selection mode. */
 
     /*
-     * Hashtables for variable traces and searches
+     * Hashtables for variable traces and searches.
      */
 
     Tcl_HashTable varTraces;	/* Hashtable holding the start of a variable's
 				 * active trace list; varPtr is the key. */
     Tcl_HashTable varSearches;	/* Hashtable holding the start of a variable's
-				 * active searches list; varPtr is the key */
+				 * active searches list; varPtr is the key. */
     /*
      * The thread-specific data ekeko: cache pointers or values that
      *  (a) do not change during the thread's lifetime
@@ -2135,9 +2150,10 @@ struct LimitHandler {
 				/* The handler callback. */
     ClientData clientData;	/* Opaque argument to the handler callback. */
     Tcl_LimitHandlerDeleteProc *deleteProc;
-				/* How to delete the clientData */
-    LimitHandler *prevPtr;	/* Previous item in linked list of handlers */
-    LimitHandler *nextPtr;	/* Next item in linked list of handlers */
+				/* How to delete the clientData. */
+    LimitHandler *prevPtr;	/* Previous item in linked list of
+				 * handlers. */
+    LimitHandler *nextPtr;	/* Next item in linked list of handlers. */
 };
 
 /*
@@ -2163,7 +2179,7 @@ struct LimitHandler {
 
 /*
  * This macro is used to properly align the memory allocated by Tcl, giving
- * the same alignment as the native malloc
+ * the same alignment as the native malloc.
  */
 
 #if defined(__APPLE__)
@@ -2203,7 +2219,7 @@ typedef enum {
 /*
  * The following enum values are used to indicate the translation of a Tcl
  * channel. Declared here so that each platform can define
- * TCL_PLATFORM_TRANSLATION to the native translation on that platform
+ * TCL_PLATFORM_TRANSLATION to the native translation on that platform.
  */
 
 typedef enum TclEolTranslation {
@@ -2450,19 +2466,21 @@ typedef struct ProcessGlobalValue {
  */
 
 #define TCL_PARSE_DECIMAL_ONLY		1
-				/* Leading zero doesn't denote octal or hex */
+				/* Leading zero doesn't denote octal or
+				 * hex. */
 #define TCL_PARSE_OCTAL_ONLY		2
-				/* Parse octal even without prefix */
+				/* Parse octal even without prefix. */
 #define TCL_PARSE_HEXADECIMAL_ONLY	4
-				/* Parse hexadecimal even without prefix */
+				/* Parse hexadecimal even without prefix. */
 #define TCL_PARSE_INTEGER_ONLY		8
-				/* Disable floating point parsing */
+				/* Disable floating point parsing. */
 #define TCL_PARSE_SCAN_PREFIXES		16
-				/* Use [scan] rules dealing with 0? prefixes */
+				/* Use [scan] rules dealing with 0?
+				 * prefixes. */
 #define TCL_PARSE_NO_WHITESPACE		32
-				/* Reject leading/trailing whitespace */
+				/* Reject leading/trailing whitespace. */
 #define TCL_PARSE_BINARY_ONLY	64
-				/* Parse binary even without prefix */
+				/* Parse binary even without prefix. */
 
 /*
  *----------------------------------------------------------------------
@@ -2609,7 +2627,7 @@ MODULE_SCOPE void	TclCleanupLiteralTable(Tcl_Interp *interp,
 			    LiteralTable *tablePtr);
 MODULE_SCOPE int	TclDoubleDigits(char *buf, double value, int *signum);
 MODULE_SCOPE void	TclDeleteNamespaceVars(Namespace *nsPtr);
-/* TIP #280 - Modified token based evulation, with line information */
+/* TIP #280 - Modified token based evulation, with line information. */
 MODULE_SCOPE int	TclEvalEx(Tcl_Interp *interp, const char *script,
 			    int numBytes, int flags, int line);
 MODULE_SCOPE int	TclFileAttrsCmd(Tcl_Interp *interp,
@@ -3502,7 +3520,7 @@ typedef const char* TclDTraceStr;
  * Invalidate the string rep first so we can use the bytes value for our
  * pointer chain, and signal an obj deletion (as opposed to shimmering) with
  * 'length == -1'.
- * Use empty 'if ; else' to handle use in unbraced outer if/else conditions
+ * Use empty 'if ; else' to handle use in unbraced outer if/else conditions.
  */
 
 # define TclDecrRefCount(objPtr) \
@@ -3527,7 +3545,7 @@ typedef const char* TclDTraceStr;
  * The PURIFY mode is like the regular mode, but instead of doing block
  * Tcl_Obj allocation and keeping a freed list for efficiency, it always
  * allocates and frees a single Tcl_Obj so that tools like Purify can better
- * track memory leaks
+ * track memory leaks.
  */
 
 #  define TclAllocObjStorageEx(interp, objPtr) \
@@ -4008,7 +4026,7 @@ MODULE_SCOPE void	TclBNInitBignumFromWideUInt(mp_int *bignum,
 
 /*
  *----------------------------------------------------------------
- * Inline version of Tcl_GetCurrentNamespace and Tcl_GetGlobalNamespace
+ * Inline version of Tcl_GetCurrentNamespace and Tcl_GetGlobalNamespace.
  */
 
 #define TclGetCurrentNamespace(interp) \
@@ -4052,11 +4070,11 @@ MODULE_SCOPE void	TclBNInitBignumFromWideUInt(mp_int *bignum,
 	    ? 1 : 0)))
 
 /*
- * Compile-time assertions: these produce a compile time error if
- * the expression is not known to be true at compile time.
- * If the assertion is known to be false, the compiler (or optimizer?) will
- * error out with "division by zero". If the assertion cannot be evaluated at
- * compile time, the compiler will error out with "non-static initializer".
+ * Compile-time assertions: these produce a compile time error if the
+ * expression is not known to be true at compile time. If the assertion is
+ * known to be false, the compiler (or optimizer?) will error out with
+ * "division by zero". If the assertion cannot be evaluated at compile time,
+ * the compiler will error out with "non-static initializer".
  *
  * Adapted with permission from
  * http://www.pixelbeat.org/programming/gcc/static_assert.html
@@ -4139,24 +4157,17 @@ typedef struct TEOV_callback {
 #define TOP_CB(iPtr) (((Interp *)(iPtr))->execEnvPtr->callbackPtr)
 
 /*
- * Inline version of Tcl_NRAddCallback
+ * Inline version of Tcl_NRAddCallback.
  */
 
-#define TclNRAddCallback(						\
-    interp,								\
-    postProcPtr,							\
-    data0,								\
-    data1,								\
-    data2,								\
-    data3)								\
-    {									\
+#define TclNRAddCallback(interp,postProcPtr,data0,data1,data2,data3) {	\
 	TEOV_callback *callbackPtr;					\
 	TCLNR_ALLOC((interp), (callbackPtr));				\
 	callbackPtr->procPtr = (postProcPtr);				\
-	callbackPtr->data[0] = (ClientData)(data0);\
-	callbackPtr->data[1] = (ClientData)(data1);\
-	callbackPtr->data[2] = (ClientData)(data2);\
-	callbackPtr->data[3] = (ClientData)(data3);\
+	callbackPtr->data[0] = (ClientData)(data0);			\
+	callbackPtr->data[1] = (ClientData)(data1);			\
+	callbackPtr->data[2] = (ClientData)(data2);			\
+	callbackPtr->data[3] = (ClientData)(data3);			\
 	callbackPtr->nextPtr = TOP_CB(interp);				\
 	TOP_CB(interp) = callbackPtr;					\
     }