Revised documentation for TIP 232

2 files changed, 29 insertions, 9 deletions

diff --git a/ChangeLog b/ChangeLog
index be42014..fcd32fc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
+2005-04-25  Kevin B. Kenny <kennykb@acm.org>
+	
+	[tcl-numerics-branch]
+
+	* doc/CrtMathFunc.n:		Revised documentation for TIP 232
+	
 2005-04-20  Kevin B. Kenny <kennykb@acm.org>
 
+	[tcl-numerics-branch]
+
 	* doc/expr.n:
 	* doc/mathfunc.n (new file):	Revised documentation for TIP 232
 	
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3
index 693b0b6..8dcb27f 100644
--- a/doc/CrtMathFnc.3
+++ b/doc/CrtMathFnc.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.11.2.1 2005/04/10 23:14:41 kennykb Exp $
+'\" RCS: @(#) $Id: CrtMathFnc.3,v 1.11.2.2 2005/04/25 19:59:45 kennykb Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
@@ -64,11 +64,19 @@ passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
 .PP
 Tcl allows a number of mathematical functions to be used in
 expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
-\fBTcl_CreateMathFunc\fR allows applications to add additional functions
+These functions are represented by commands in the namespace,
+\fBtcl::mathfunc\fR.  The \fBTcl_CreateMathFunc\fR function is
+an obsolete way for applications to add additional functions
 to those already provided by Tcl or to replace existing functions.
+It should not be used by new applications, which should create
+math functions using \fBTcl_CreateObjCommand\fR to create a command
+in the \fBtcl::mathfunc\fR namespace.
+.PP
+In the \fBTcl_CreateMathFunc\fR interface,
 \fIName\fR is the name of the function as it will appear in expressions.
-If \fIname\fR doesn't already exist as a function then a new function
-is created.  If it does exist, then the existing function is replaced.
+If \fIname\fR doesn't already exist in the \fB::tcl::mathfunc\fR
+namespace, then a new command is created in that namespace.
+If \fIname\fR does exist, then the existing function is replaced.
 \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
 Each entry in the \fIargTypes\fR array must be
 one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR,
@@ -130,10 +138,14 @@ result.
 If an error did not occur, the array reference placed in the variable
 pointed to by \fIargTypesPtr\fR is newly allocated, and should be
 released by passing it to \fBTcl_Free\fR.  Some functions (the
-standard set implemented in the core) are implemented directly at the
-bytecode level; attempting to retrieve values for them causes a NULL
-to be stored in the variable pointed to by \fIprocPtr\fR and the
-variable pointed to by \fIclientDataPtr\fR will not be modified.
+standard set implemented in the core, and those defined by placing
+commands in the \fBtcl::mathfunc\fR namespace) do not have
+argument type information; attempting to retrieve values for
+them causes a NULL to be stored in the variable pointed to by 
+\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
+will not be modified.  The variable pointed to by \fInumArgsPointer\fR
+will contain -1, and no argument types will be stored in the variable
+pointed to by \fIargTypesPointer\fR.
 .PP
 \fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all
 the math functions defined in the interpreter whose name matches
@@ -145,4 +157,4 @@ object will have a reference count of zero.
 expression, mathematical function
 
 .SH "SEE ALSO"
-expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)
+expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)