code review and inline documentation

6 files changed, 288 insertions, 26 deletions

diff --git a/generic/tclClock.c b/generic/tclClock.c
index a324b65..fc7c70c 100644
--- a/generic/tclClock.c
+++ b/generic/tclClock.c
@@ -167,7 +167,6 @@ static const struct ClockCommand clockCommands[] = {
     { "GetJulianDayFromEraYearWeekDay",
 		ClockGetjuliandayfromerayearweekdayObjCmd },
     { "ParseFormatArgs",	ClockParseformatargsObjCmd },
-    { "_test",			TclStrIdxTreeTestObjCmd },
     { NULL, NULL }
 };
 
@@ -262,10 +261,11 @@ TclClockInit(
 /*
  *----------------------------------------------------------------------
  *
- * ClockDeleteCmdProc --
+ * ClockConfigureClear --
  *
- *	Remove a reference to the clock client data, and clean up memory
- *	when it's all gone.
+ *	Clean up cached resp. run-time storages used in clock commands.
+ *
+ *	Shared usage for clean-up (ClockDeleteCmdProc) and "configure -clear".
  *
  * Results:
  *	None.
@@ -301,7 +301,20 @@ ClockConfigureClear(
     Tcl_UnsetObjRef(data->UTC2Local.tzName);
     Tcl_UnsetObjRef(data->Local2UTC.timezoneObj);
 }
-
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockDeleteCmdProc --
+ *
+ *	Remove a reference to the clock client data, and clean up memory
+ *	when it's all gone.
+ *
+ * Results:
+ *	None.
+ *
+ *----------------------------------------------------------------------
+ */
 static void
 ClockDeleteCmdProc(
     ClientData clientData)	/* Opaque pointer to the client data */
@@ -335,7 +348,20 @@ ClockDeleteCmdProc(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * NormTimezoneObj --
+ *
+ *	Normalizes the timezone object (used for caching puposes).
+ *
+ *	If already cached time zone could be found, returns this
+ *	object (last setup or last used, system (current) or gmt).
+ *
+ * Results:
+ *	Normalized tcl object pointer.
+ *
+ *----------------------------------------------------------------------
  */
+
 static inline Tcl_Obj *
 NormTimezoneObj(
     ClockClientData *dataPtr,  /* Client data containing literal pool */
@@ -411,9 +437,23 @@ ClockGetCurrentLocale(
 
     return dataPtr->CurrentLocale;
 }
+
 /*
  *----------------------------------------------------------------------
+ *
+ * NormLocaleObj --
+ *
+ *	Normalizes the locale object (used for caching puposes).
+ *
+ *	If already cached locale could be found, returns this
+ *	object (current, system (OS) or last used locales).
+ *
+ * Results:
+ *	Normalized tcl object pointer.
+ *
+ *----------------------------------------------------------------------
  */
+
 static Tcl_Obj *
 NormLocaleObj(
     ClockClientData *dataPtr,	/* Client data containing literal pool */
@@ -494,7 +534,21 @@ NormLocaleObj(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockMCDict --
+ *
+ *	Retrieves a localized storage dictionary object for the given 
+ *	locale object.
+ *
+ *	This corresponds with call `::tcl::clock::mcget locale`.
+ *	Cached representation stored in options (for further access).
+ *
+ * Results:
+ *	Tcl-object contains smart reference to msgcat dictionary.
+ *
+ *----------------------------------------------------------------------
  */
+
 MODULE_SCOPE Tcl_Obj *
 ClockMCDict(ClockFmtScnCmdArgs *opts)
 {
@@ -560,6 +614,21 @@ ClockMCDict(ClockFmtScnCmdArgs *opts)
     return opts->mcDictObj;
 }
 
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockMCGet --
+ *
+ *	Retrieves a msgcat value for the given literal integer mcKey
+ *	from localized storage (corresponding given locale object)
+ *	by mcLiterals[mcKey] (e. g. MONTHS_FULL).
+ *
+ * Results:
+ *	Tcl-object contains localized value.
+ *
+ *----------------------------------------------------------------------
+ */
+
 MODULE_SCOPE Tcl_Obj *
 ClockMCGet(
     ClockFmtScnCmdArgs *opts, 
@@ -581,6 +650,21 @@ ClockMCGet(
     return valObj; /* or NULL in obscure case if Tcl_DictObjGet failed */
 }
 
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockMCGetIdx --
+ *
+ *	Retrieves an indexed msgcat value for the given literal integer mcKey
+ *	from localized storage (corresponding given locale object)
+ *	by mcLitIdxs[mcKey] (e. g. _IDX_MONTHS_FULL).
+ *
+ * Results:
+ *	Tcl-object contains localized indexed value.
+ *
+ *----------------------------------------------------------------------
+ */
+
 MODULE_SCOPE Tcl_Obj *
 ClockMCGetIdx(
     ClockFmtScnCmdArgs *opts, 
@@ -609,6 +693,21 @@ ClockMCGetIdx(
 
     return valObj;
 }
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockMCSetIdx --
+ *
+ *	Sets an indexed msgcat value for the given literal integer mcKey
+ *	in localized storage (corresponding given locale object)
+ *	by mcLitIdxs[mcKey] (e. g. _IDX_MONTHS_FULL).
+ *
+ * Results:
+ *	Returns a standard Tcl result.
+ *
+ *----------------------------------------------------------------------
+ */
 
 MODULE_SCOPE int
 ClockMCSetIdx(
@@ -639,7 +738,23 @@ ClockMCSetIdx(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockConfigureObjCmd --
+ *
+ *	This function is invoked to process the Tcl "clock configure" command.
+ *
+ * Usage:
+ *	::tcl::clock::configure ?-option ?value??
+ *
+ * Results:
+ *	Returns a standard Tcl result.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
  */
+
 static int
 ClockConfigureObjCmd(
     ClientData clientData,  /* Client data containing literal pool */
@@ -781,7 +896,20 @@ ClockConfigureObjCmd(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockGetTZData --
+ *
+ *	Retrieves tzdata table for given normalized timezone.
+ *
+ * Results:
+ *	Returns a tcl object with tzdata.
+ *
+ * Side effects:
+ *	The tzdata can be cached in ClockClientData structure.
+ *
+ *----------------------------------------------------------------------
  */
+
 static inline Tcl_Obj *
 ClockGetTZData(
     ClientData clientData,	/* Opaque pointer to literal pool, etc. */
@@ -839,9 +967,20 @@ ClockGetTZData(
     }
     return ret;
 }
+
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockGetSystemTimeZone --
+ *
+ *	Returns system (current) timezone.
+ *
+ * Results:
+ *	Returns normalized timezone object.
+ *
+ *----------------------------------------------------------------------
  */
+
 static Tcl_Obj *
 ClockGetSystemTimeZone(
     ClientData clientData,	/* Opaque pointer to literal pool, etc. */
@@ -869,9 +1008,20 @@ ClockGetSystemTimeZone(
     }
     return dataPtr->SystemTimeZone;
 }
+
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockSetupTimeZone --
+ *
+ *	Sets up the timezone. Loads tzdata, etc.
+ *
+ * Results:
+ *	Returns normalized timezone object.
+ *
+ *----------------------------------------------------------------------
  */
+
 MODULE_SCOPE Tcl_Obj *
 ClockSetupTimeZone(
     ClientData clientData,	/* Opaque pointer to literal pool, etc. */
@@ -908,20 +1058,22 @@ ClockSetupTimeZone(
     }
     return NULL;
 }
+
 /*
  *----------------------------------------------------------------------
- * ClockFormatNumericTimeZone -
  *
- *   Formats a time zone as +hhmmss
+ * ClockFormatNumericTimeZone --
+ *
+ *	Formats a time zone as +hhmmss
  *
  * Parameters:
- *   z - Time zone in seconds east of Greenwich
+ *	z - Time zone in seconds east of Greenwich
  *
  * Results:
- *   Returns the time zone object (formatted in a numeric form)
+ *	Returns the time zone object (formatted in a numeric form)
  *
  * Side effects:
- *   None.
+ *	None.
  *
  *----------------------------------------------------------------------
  */
@@ -943,6 +1095,7 @@ ClockFormatNumericTimeZone(int z) {
     }
     return Tcl_ObjPrintf("%c%02d%02d", sign, h, m);
 }
+
 /*
  *----------------------------------------------------------------------
  *
@@ -1145,7 +1298,20 @@ ClockGetdatefieldsObjCmd(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * ClockGetDateFields --
+ *
+ *	Converts given UTC time (seconds in a TclDateFields structure) 
+ *	to local time and determines the values that clock routines will 
+ *	use in scanning or formatting a date.
+ *
+ * Results:
+ *	Date-time values are stored in structure "fields".
+ *	Returns a standard Tcl result.
+ *
+ *----------------------------------------------------------------------
  */
+
 int
 ClockGetDateFields(
     ClientData clientData,	/* Client data of the interpreter */
@@ -1586,6 +1752,7 @@ ConvertLocalToUTCUsingTable(
     fields->seconds = fields->localSeconds - fields->tzOffset;
 
 #if 0
+    /* currently unused, test purposes only */
     /*
      * Convert back from UTC, if local times are different - wrong local time
      * (local time seems to be in between DST-hole).
@@ -2404,9 +2571,24 @@ GetJulianDayFromEraYearMonthDay(
 		+ ym1o4;
     }
 }
+
 /*
  *----------------------------------------------------------------------
+ *
+ * GetJulianDayFromEraYearDay --
+ *
+ *	Given era, year, and dayOfYear (in TclDateFields), and the
+ *	Gregorian transition date, computes the Julian Day Number.
+ *
+ * Results:
+ *	None.
+ *
+ * Side effects:
+ *	Stores day number in 'julianDay'
+ *
+ *----------------------------------------------------------------------
  */
+
 
 MODULE_SCOPE void
 GetJulianDayFromEraYearDay(
@@ -2740,6 +2922,19 @@ ClockMicrosecondsObjCmd(
     return TCL_OK;
 }
 
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * _ClockParseFmtScnArgs --
+ *
+ *	Parses the arguments for [clock scan] and [clock format].
+ *
+ * Results:
+ *	Returns a standard Tcl result, and stores parsed options
+ *	(format, the locale, timezone and base) in structure "opts".
+ *
+ *-----------------------------------------------------------------------------
+ */
 
 static int
 _ClockParseFmtScnArgs(
@@ -2853,9 +3048,7 @@ _ClockParseFmtScnArgs(
  *	Returns a standard Tcl result, whose value is a four-element list
  *	comprising the time format, the locale, and the timezone.
  *
- * This function exists because the loop that parses the [clock format]
- * options is a known performance "hot spot", and is implemented in an effort
- * to speed that particular code up.
+ * This function exists for backward compatibility purposes.
  *
  *-----------------------------------------------------------------------------
  */
@@ -2919,7 +3112,20 @@ ClockParseformatargsObjCmd(
 
 /*----------------------------------------------------------------------
  *
- * ClockFormatObjCmd -
+ * ClockFormatObjCmd -- , clock format --
+ *
+ *	This function is invoked to process the Tcl "clock format" command.
+ *
+ *	Formats a count of seconds since the Posix Epoch as a time of day.
+ *
+ *	The 'clock format' command formats times of day for output.  Refer 
+ *	to the user documentation to see what it does.
+ *
+ * Results:
+ *	Returns a standard Tcl result.
+ *
+ * Side effects:
+ *	None.
  *
  *----------------------------------------------------------------------
  */
@@ -3018,7 +3224,20 @@ done:
 
 /*----------------------------------------------------------------------
  *
- * ClockScanObjCmd -
+ * ClockScanObjCmd -- , clock scan --
+ *
+ *	This function is invoked to process the Tcl "clock scan" command.
+ *
+ *	Inputs a count of seconds since the Posix Epoch as a time of day.
+ *
+ *	The 'clock scan' command scans times of day on input. Refer to the
+ *	user documentation to see what it does.
+ *
+ * Results:
+ *	Returns a standard Tcl result.
+ *
+ * Side effects:
+ *	None.
  *
  *----------------------------------------------------------------------
  */
@@ -3188,7 +3407,20 @@ done:
 }
 
 /*----------------------------------------------------------------------
+ *
+ * ClockFreeScan --
+ *
+ *	Used by ClockScanObjCmd for free scanning without format.
+ *
+ * Results:
+ *	Returns a standard Tcl result.
+ *
+ * Side effects:
+ *	None.
+ *
+ *----------------------------------------------------------------------
  */
+
 int
 ClockFreeScan(
     ClientData clientData,	/* Client data containing literal pool */
diff --git a/generic/tclClockFmt.c b/generic/tclClockFmt.c
index 24c0f1d..ff16714 100644
--- a/generic/tclClockFmt.c
+++ b/generic/tclClockFmt.c
@@ -881,6 +881,7 @@ ObjListSearch(ClockFmtScnCmdArgs *opts,
     return TCL_RETURN;
 }
 #if 0
+/* currently unused */
 
 static int 
 LocaleListSearch(ClockFmtScnCmdArgs *opts, 
@@ -1042,6 +1043,7 @@ ClockStrIdxTreeSearch(ClockFmtScnCmdArgs *opts,
     return TCL_OK;
 }
 #if 0
+/* currently unused */
 
 static int 
 StaticListSearch(ClockFmtScnCmdArgs *opts, 
@@ -1093,6 +1095,7 @@ ClockScnToken_Month_Proc(ClockFmtScnCmdArgs *opts,
     DateInfo *info, ClockScanToken *tok)
 {
 #if 0
+/* currently unused, test purposes only */
     static const char * months[] = {
 	/* full */
 	"January", "February", "March",
diff --git a/generic/tclDate.h b/generic/tclDate.h
index cf307a6..1519842 100644
--- a/generic/tclDate.h
+++ b/generic/tclDate.h
@@ -509,11 +509,4 @@ MODULE_SCOPE int    ClockFormat(register DateFormat *dateFmt,
 
 MODULE_SCOPE void   ClockFrmScnClearCaches(void);
 
-/*
- * Other externals.
- */
-
-MODULE_SCOPE unsigned long TclEnvEpoch; /* Epoch of the tcl environment 
-					 * (if changed with tcl-env). */
-
 #endif /* _TCLCLOCK_H */
diff --git a/generic/tclDictObj.c b/generic/tclDictObj.c
index caebbf1..b786c4f 100644
--- a/generic/tclDictObj.c
+++ b/generic/tclDictObj.c
@@ -1960,6 +1960,32 @@ DictSizeCmd(
 
 /*
  *----------------------------------------------------------------------
+ *
+ * Tcl_DictObjSmartRef --
+ *
+ *	This function returns new tcl-object with the smart reference to
+ *	dictionary object.
+ *
+ *	Object returned with this function is a smart reference (pointer),
+ *	so new object of type tclDictType, that directly references given
+ *	dictionary object (with internally increased refCount).
+ *
+ *	The usage of such pointer objects allows to hold more as one
+ *	reference to the same real dictionary object, allows to make a pointer
+ *	to part of another dictionary, allows to change the dictionary without
+ *	regarding of the "shared" state of the dictionary object.
+ *
+ *	Prevents "called with shared object" exception if object is multiple
+ *	referenced.
+ *
+ * Results:
+ *	The newly create object (contains smart reference) is returned.
+ *	The returned object has a ref count of 0.
+ *
+ * Side effects:
+ *	Increases ref count of the referenced dictionary.
+ *
+ *----------------------------------------------------------------------
  */
 
 Tcl_Obj *
@@ -1991,9 +2017,9 @@ Tcl_DictObjSmartRef(
  *
  * DictSmartRefCmd --
  *
- *	This function implements the "dict smartref" Tcl command. See the user
- *	documentation for details on what it does, and TIP#111 for the formal
- *	specification.
+ *	This function implements the "dict smartref" Tcl command.
+ *
+ *	See description of Tcl_DictObjSmartRef for details.
  *
  * Results:
  *	A standard Tcl result.
diff --git a/generic/tclInt.h b/generic/tclInt.h
index a569788..15cb355 100644
--- a/generic/tclInt.h
+++ b/generic/tclInt.h
@@ -4886,6 +4886,13 @@ typedef struct NRE_callback {
 #define Tcl_Free(ptr)                 TclpFree(ptr)
 #endif
 
+/*
+ * Other externals.
+ */
+
+MODULE_SCOPE unsigned long TclEnvEpoch; /* Epoch of the tcl environment 
+                                         * (if changed with tcl-env). */
+
 #endif /* _TCLINT */
 
 /*
diff --git a/generic/tclStrIdxTree.c b/generic/tclStrIdxTree.c
index 686c1e4..773eb6a 100644
--- a/generic/tclStrIdxTree.c
+++ b/generic/tclStrIdxTree.c
@@ -418,7 +418,8 @@ TclStrIdxTreeGetFromObj(Tcl_Obj *objPtr) {
 /*
  * Several debug primitives
  */
-#if 1
+#if 0
+/* currently unused, debug resp. test purposes only */
 
 void 
 TclStrIdxTreePrint(