Reinforced the description of the requirement for the tables of names for Tcl_GetIndexFromObj to index over to be static, following posting to tcl-core by Brian Griffin about a bug caused by not obeying this rule correctly.

FossilOrigin-Name: dfd2b68795a3fc7978ac7da12d0ce8cd2bc7bb47

2 files changed, 16 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 28ff688..a39e72d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2012-06-29  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/GetIndex.3: Reinforced the description of the requirement for
+	the tables of names to index over to be static, following posting to
+	tcl-core by Brian Griffin about a bug caused by Tktreectrl not obeying
+	this rule correctly. This does not represent a functionality change,
+	merely a clearer documentation of a long-standing constraint.
+
 2012-06-23  Jan Nijtmans  <nijtmans@users.sf.net>
 
 	* unix/tclUnixNotfy.c: [Bug 3508771]: Cygwin notifier for handling
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index e47f89b..54ac034 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -34,10 +34,16 @@ table entry.
 .AP "CONST char" **tablePtr in
 An array of null-terminated strings.  The end of the array is marked
 by a NULL string pointer.
+Note that references to the \fItablePtr\fR may be retained in the
+internal representation of \fIobjPtr\fR, so this should represent the
+address of a statically-allocated array.
 .AP "CONST VOID" *structTablePtr in
 An array of arbitrary type, typically some \fBstruct\fP type.
 The first member of the structure must be a null-terminated string.
 The size of the structure is given by \fIoffset\fP.
+Note that references to the \fIstructTablePtr\fR may be retained in the
+internal representation of \fIobjPtr\fR, so this should represent the
+address of a statically-allocated array of structures.
 .VS
 .AP int offset in
 The offset to add to structTablePtr to get to the next entry.
@@ -56,10 +62,10 @@ The index of the string in \fItablePtr\fR that matches the value of
 
 .SH DESCRIPTION
 .PP
-This procedure provides an efficient way for looking up keywords,
+These procedures provide an efficient way for looking up keywords,
 switch names, option names, and similar things where the value of
 an object must be one of a predefined set of values.
-\fIObjPtr\fR is compared against each of
+\fBTcl_GetIndexFromObj\fR compares \fIobjPtr\fR against each of
 the strings in \fItablePtr\fR to find a match.  A match occurs if
 \fIobjPtr\fR's string value is identical to one of the strings in
 \fItablePtr\fR, or if it is a non-empty unique abbreviation