Documentation update

8 files changed, 12 insertions, 19 deletions

diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index 5aa541b..3dd626a 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -48,7 +48,7 @@ Points to space where the number of bytes in the array may be written.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the size of the byte array is larger than INT_MAX (which should
+NULL for byte arrays larger than INT_MAX (which should
 trigger proper error-handling), otherwise expect it to crash.
 .BE
 .SH DESCRIPTION
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 7469a78..4a25d84 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -76,7 +76,7 @@ contained within the dictionary placed within it.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the size of the dictionary is larger than INT_MAX (which should
+NULL for dictionaries larger than INT_MAX (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_DictSearch *searchPtr in/out
 Pointer to record to use to keep track of progress in enumerating all
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index b8766e7..2076c96 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -274,7 +274,7 @@ Filled with the number of elements in the split path.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the number of elements is larger than INT_MAX (which should
+NULL for paths having more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Obj *basePtr in
 The base path on to which to join the given elements. May be NULL.
diff --git a/doc/ListObj.3 b/doc/ListObj.3
index 220cd08..74cbe9a 100644
--- a/doc/ListObj.3
+++ b/doc/ListObj.3
@@ -65,7 +65,7 @@ stores the number of element values in \fIlistPtr\fR.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the list size is larger than INT_MAX (which should
+NULL for lists with more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Obj ***objvPtr out
 A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
@@ -87,7 +87,7 @@ stores the length of the list.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the list size is larger than INT_MAX (which should
+TCL_ERROR for lists with more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP Tcl_Size index in
 Index of the list element that \fBTcl_ListObjIndex\fR
@@ -174,9 +174,6 @@ Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
 .PP
 \fBTcl_ListObjLength\fR returns the number of elements in the list value
 referenced by \fIlistPtr\fR.
-It returns this count by storing a value in the address \fIlengthPtr\fR.
-If \fIlengthPtr\fR points to a variable of type \fBint\fR and the list
-contains more than 2**31 elements, the function returns \fBTCL_ERROR\fR.
 If the value is not already a list value,
 \fBTcl_ListObjLength\fR will attempt to convert it to one;
 if the conversion fails, it returns \fBTCL_ERROR\fR
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index ca6f52d..4fdf0b0 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -28,7 +28,7 @@ stored in \fIremObjv\fR.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the number of elements is larger than INT_MAX (which should
+NULL for argument lists with more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP "Tcl_Obj *const" *objv in
 The array of arguments to be parsed.
diff --git a/doc/SplitList.3 b/doc/SplitList.3
index 9f43731..0036333 100644
--- a/doc/SplitList.3
+++ b/doc/SplitList.3
@@ -43,7 +43,7 @@ Filled in with number of elements in \fIlist\fR.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the list size is larger than INT_MAX (which should
+TCL_ERROR for lists with more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index f55ee3c..663b336 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.3
@@ -29,8 +29,8 @@ File path in a form appropriate for the current platform (see the
 Filled in with number of path elements in \fIpath\fR.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
-If your extensions is compiled with -DTCL_8_API, this function will return
-NULL if the number of elements is larger than INT_MAX (which should
+If your extensions is compiled with -DTCL_8_API, argcPtr will be filled
+with -1 for paths with more than INT_MAX elements (which should
 trigger proper error-handling), otherwise expect it to crash.
 .AP "const char" ***argvPtr out
 \fI*argvPtr\fR will be filled in with the address of an array of
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 305af9a..fc5f5d6 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -124,8 +124,7 @@ of a value's string representation.
 May be (Tcl_Size *)NULL when not used. If it points to a variable which
 type is not \fBTcl_Size\fR, a compiler warning will be generated.
 If your extensions is compiled with -DTCL_8_API, this function will
-panic if the number of elements is larger than INT_MAX (which should
-trigger proper error-handling), otherwise expect it to crash.
+panic for strings with more than INT_MAX bytes/characters, otherwise expect it to crash.
 .AP "const char" *string in
 Null-terminated string value to append to \fIobjPtr\fR.
 .AP Tcl_Size limit in
@@ -190,9 +189,7 @@ Even in the limited situations where writing to this pointer is
 acceptable, one should take care to respect the copy-on-write
 semantics required by \fBTcl_Obj\fR's, with appropriate calls
 to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
-in-place modification of the string representation. If \fIlengthPtr\fR
-points to an \fBint\fR variable, and the string has more than 2^31 bytes,
-a panic will result.
+in-place modification of the string representation.
 The procedure \fBTcl_GetString\fR is used in the common case
 where the caller does not need the length of the string
 representation.
@@ -204,8 +201,7 @@ value as a Unicode string.  This is given by the returned pointer and
 byte pointer is owned by the value manager and should not be modified by
 the caller.  The procedure \fBTcl_GetUnicode\fR is used in the common case
 where the caller does not need the length of the unicode string
-representation. If \fIlengthPtr\fR points to an \fBint\fR variable,
-and the string has more than 2^31 unicode characters, a panic will result.
+representation.
 .PP
 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
 value's Unicode representation. If the index is out of range or