Documenting our reference count management

3 files changed, 29 insertions, 1 deletions

diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
index 09400c8..2a7d7a3 100644
--- a/doc/ByteArrObj.3
+++ b/doc/ByteArrObj.3
@@ -85,6 +85,18 @@ newly allocated bytes at the end of the array have arbitrary values.  If
 the length of array is reduced to the new length.  The return value is a
 pointer to the value's new array of bytes.
 
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
+like \fBTcl_NewObj\fR.
+.PP
+\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the
+reference count of their \fIobjPtr\fR arguments, but do require that the
+object be unshared.
+.PP
+\fBTcl_GetByteArrayFromObj\fR does not modify the reference count of its
+\fIobjPtr\fR argument; it only reads.
+
 .SH "SEE ALSO"
 Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
 
diff --git a/doc/Cancel.3 b/doc/Cancel.3
index 847707e..73edaf6 100644
--- a/doc/Cancel.3
+++ b/doc/Cancel.3
@@ -67,6 +67,14 @@ other procedures.  If an error is returned and this bit is set in
 result, where it can be retrieved with \fBTcl_GetObjResult\fR or
 \fBTcl_GetStringResult\fR.  If this flag bit is not set then no error
 message is left and the interpreter's result will not be modified.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CancelEval\fR always decrements the reference count of its
+\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to
+be usually called with an object with zero reference count. If the
+object is shared with some other location (including the Tcl
+evaluation stack) it should have its reference count incremented
+before calling this function.
 .SH "SEE ALSO"
 interp(n), Tcl_Eval(3),
 TIP 285
diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3
index 92f9b0c..2623dcd 100644
--- a/doc/CrtAlias.3
+++ b/doc/CrtAlias.3
@@ -243,8 +243,16 @@ any script evaluation mechanism will fail.
 .PP
 For a description of the Tcl interface to multiple interpreters, see
 \fIinterp(n)\fR.
+.SH "REFERENCE COUNT MANAGEMENT"
+.PP
+\fBTcl_CreateAliasObj\fR increments the reference counts of the values
+in its \fIobjv\fR argument. (That reference lasts the same length of
+time as the owning alias.)
+.PP
+\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a
+pointer to values that it holds a reference to.
 .SH "SEE ALSO"
-interp
+interp(n)
 
 .SH KEYWORDS
 alias, command, exposed commands, hidden commands, interpreter, invoke,