* doc/DoubleObj.3: More doc updates for TIP 237.

        * doc/scan.n:

        * generic/tclScan.c:    [scan $s %u] is documented to accept only
        * tests/scan.test:      decimal formatted integers.  Fixed code to
        match.

1 files changed, 27 insertions, 40 deletions

diff --git a/doc/DoubleObj.3 b/doc/DoubleObj.3
index 4af284d..ea62c07 100644
--- a/doc/DoubleObj.3
+++ b/doc/DoubleObj.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: DoubleObj.3,v 1.3 2004/09/06 09:44:56 dkf Exp $
+'\" RCS: @(#) $Id: DoubleObj.3,v 1.4 2006/04/25 17:15:25 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
@@ -25,55 +25,42 @@ int
 .SH ARGUMENTS
 .AS Tcl_Interp doubleValue in/out
 .AP double doubleValue in
-A double-precision floating-point value used to initialize or set a double object.
+A double-precision floating-point value used to initialize or set a Tcl object.
 .AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
-to double type.
+For \fBTcl_SetDoubleObj\fR, this points to the object in which to store a
+double value.
 For \fBTcl_GetDoubleFromObj\fR, this refers to the object
-from which to get a double value; 
-if \fIobjPtr\fR does not already point to a double object,
-an attempt will be made to convert it to one.
+from which to retrieve a double value. 
 .AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
-an error message is left in the interpreter's result object
-unless \fIinterp\fR is NULL.
+When non-NULL, an error message is left here when double value retrieval fails.
 .AP double *doublePtr out
-Points to place to store the double value
-obtained from \fIobjPtr\fR.
+Points to place to store the double value obtained from \fIobjPtr\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
-These procedures are used to create, modify, and read
-double Tcl objects from C code.
-\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
-will create a new object of double type
-or modify an existing object to have double type. 
-Both of these procedures set the object to have the
-double-precision floating-point value given by \fIdoubleValue\fR;
-\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be double
-and assign the double value to the object's internal representation
-\fIdoubleValue\fR member.
-\fBTcl_SetDoubleObj\fR invalidates any old string representation
-and, if the object is not already a double object,
-frees any old internal representation.
+These procedures are used to create, modify, and read Tcl objects that
+hold double-precision floating-point values.
 .PP
-\fBTcl_GetDoubleFromObj\fR attempts to return a double value
-from the Tcl object \fIobjPtr\fR.
-If the object is not already a double object,
-it will attempt to convert it to one.
-If an error occurs during conversion, it returns \fBTCL_ERROR\fR
-and leaves an error message in the interpreter's result object
-unless \fIinterp\fR is NULL.
-Otherwise, it returns \fBTCL_OK\fR and stores the double value
-in the address given by \fIdoublePtr\fR.
-If the object is not already a double object,
-the conversion will free any old internal representation.
-
+\fBTcl_NewDoubleObj\fR creates and returns a new Tcl object initialized to
+the double value \fIdoubleValue\fR.  The returned Tcl object is unshared.
+.PP
+\fBTcl_SetDoubleObj\fR sets the value of an existing Tcl object pointed to
+by \fIobjPtr\fR to the double value \fIdoubleValue\fR.  The \fIobjPtr\fR
+argument must point to an unshared Tcl object.  Any attempt to set the value
+of a shared Tcl object violates Tcl's copy-on-write policy.  Any existing
+string representation or internal representation in the unshared Tcl object
+will be freed as a consequence of setting the new value.
+.PP
+\fBTcl_GetDoubleFromObj\fR attempts to retreive a double value from the
+Tcl object \fIobjPtr\fR.  If the attempt succeeds, then \fBTCL_OK\fR is
+returned, and the double value is written to the storage pointed to by
+\fIdoublePtr\fR.  If the attempt fails, then \fBTCL_ERROR\fR is returned,
+and if \fIinterp\fR is non-NULL, an error message is left in \fIinterp\fR.
+The \fBTcl_ObjType\fR of \fIobjPtr\fR may be changed to make subsequent
+calls to \fBTcl_GetDoubleFromObj\fR more efficient. 
+'\" TODO: add discussion of treatment of NaN value
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
-
 .SH KEYWORDS
 double, double object, double type, internal representation, object, object type, string representation