Documenting our reference count management

3 files changed, 18 insertions, 0 deletions

diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3
index def55de..5ca9fa5 100644
--- a/doc/ParseArgs.3
+++ b/doc/ParseArgs.3
@@ -189,6 +189,12 @@ will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked
 to the lifetime of the string representation of the argument value that it
 came from, and so should be copied if it needs to be retained. The
 \fIsrcPtr\fR and \fIclientData\fR fields are ignored.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The values in the \fiobjv\fR argument to \fBTcl_ParseArgsObjv\fR will not have
+their reference counts modified by this function. The interpreter result may
+be modified on error; the values passed should not be the interpreter result
+with no further reference added.
 .SH "SEE ALSO"
 Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
 .SH KEYWORDS
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index 40a0818..03b97f7 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -191,6 +191,7 @@ code with one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR,
 some other integer value originating in an extension.
 In addition, a result value or error message is left in \fIinterp\fR's
 result; it can be retrieved using \fBTcl_GetObjResult\fR.
+.SS "DEPRECATED FUNCTIONS"
 .PP
 \fBTcl_EvalTokens\fR differs from \fBTcl_EvalTokensStandard\fR only in
 the return convention used: it returns the result in a new Tcl_Obj.
@@ -463,5 +464,12 @@ There are additional fields in the Tcl_Parse structure after the
 \fBTcl_ParseCommand\fR, \fBTcl_ParseExpr\fR, \fBTcl_ParseBraces\fR,
 \fBTcl_ParseQuotedString\fR, and \fBTcl_ParseVarName\fR; they should not be
 referenced by code outside of these procedures.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The result of \fBTcl_EvalTokens\fR is an unshared value with a reference count
+of 1; the caller of that function should call \fBTcl_DecrRefCount\fR on the
+result value to dispose of it. (The equivalent with
+\fBTcl_EvalTokenStandard\fR is just the interpreter result, which can be
+retrieved with \fBTcl_GetObjResult\fR.)
 .SH KEYWORDS
 backslash substitution, braces, command, expression, parse, token, variable substitution
diff --git a/doc/PkgRequire.3 b/doc/PkgRequire.3
index f32c936..77e73f1 100644
--- a/doc/PkgRequire.3
+++ b/doc/PkgRequire.3
@@ -91,6 +91,10 @@ functions.
 \fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
 multiple requirements. The other forms are present for backward
 compatibility and translate their invocations to this form.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+The requirements values given (in the \fIobjv\fR argument) to
+\fBTcl_PkgRequireProc\fR must have non-zero reference counts.
 .SH KEYWORDS
 package, present, provide, require, version
 .SH "SEE ALSO"