From 1186f701edb58e2b02cd55a8ba71a3bbc00032d8 Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Sat, 2 Oct 2010 11:37:02 +0000
Subject: Add function-header comments.

---
 generic/tclObj.c | 51 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/generic/tclObj.c b/generic/tclObj.c
index 58de5d5..4c9bd98 100644
--- a/generic/tclObj.c
+++ b/generic/tclObj.c
@@ -13,7 +13,7 @@
  * See the file "license.terms" for information on usage and redistribution of
  * this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
- * RCS: @(#) $Id: tclObj.c,v 1.176 2010/10/01 12:52:49 dkf Exp $
+ * RCS: @(#) $Id: tclObj.c,v 1.177 2010/10/02 11:37:02 dkf Exp $
  */
 
 #include "tclInt.h"
@@ -55,9 +55,9 @@ char *tclEmptyStringRep = &tclEmptyString;
 
 #if defined(TCL_MEM_DEBUG) && defined(TCL_THREADS)
 /*
- * Structure for tracking the source file and line number where a given Tcl_Obj
- * was allocated.  We also track the pointer to the Tcl_Obj itself, for sanity
- * checking purposes.
+ * Structure for tracking the source file and line number where a given
+ * Tcl_Obj was allocated.  We also track the pointer to the Tcl_Obj itself,
+ * for sanity checking purposes.
  */
 
 typedef struct ObjData {
@@ -1486,7 +1486,7 @@ TclFreeObj(
 	}
     }
 }
-#endif
+#endif /* TCL_MEM_DEBUG */
 
 /*
  *----------------------------------------------------------------------
@@ -1512,7 +1512,6 @@ TclObjBeingDeleted(
 {
     return (objPtr->length == -1);
 }
-
 
 /*
  *----------------------------------------------------------------------
@@ -1706,7 +1705,6 @@ Tcl_InvalidateStringRep(
 {
     TclInvalidateStringRep(objPtr);
 }
-
 
 /*
  *----------------------------------------------------------------------
@@ -3259,7 +3257,7 @@ UpdateStringOfBignum(
 	Tcl_Panic("conversion failure in UpdateStringOfBignum");
     }
     objPtr->bytes = stringVal;
-    objPtr->length = size - 1;	/* size includes a trailing null byte */
+    objPtr->length = size - 1;	/* size includes a trailing NUL byte. */
 }
 
 /*
@@ -3566,6 +3564,24 @@ Tcl_SetBignumObj(
     TclSetBignumIntRep(objPtr, bignumValue);
 }
 
+/*
+ *----------------------------------------------------------------------
+ *
+ * TclSetBignumIntRep --
+ *
+ *	Install a bignum into the internal representation of an object.
+ *
+ * Results:
+ *	None.
+ *
+ * Side effects:
+ *	Object internal representation is updated and object type is set. The
+ *	bignum value is cleared, since ownership has transferred to the
+ *	object.
+ *
+ *----------------------------------------------------------------------
+ */
+
 void
 TclSetBignumIntRep(
     Tcl_Obj *objPtr,
@@ -3576,8 +3592,9 @@ TclSetBignumIntRep(
 
     /*
      * Clear the mp_int value.
-     * Don't call mp_clear() because it would free the digit array
-     * we just packed into the Tcl_Obj.
+     *
+     * Don't call mp_clear() because it would free the digit array we just
+     * packed into the Tcl_Obj.
      */
 
     bignumValue->dp = NULL;
@@ -3590,9 +3607,17 @@ TclSetBignumIntRep(
  *
  * TclGetNumberFromObj --
  *
+ *      Extracts a number (of any possible numeric type) from an object.
+ *
  * Results:
+ *      Whether the extraction worked. The type is stored in the variable
+ *      referred to by the typePtr argument, and a pointer to the
+ *      representation is stored in the variable referred to by the
+ *      clientDataPtr.
  *
  * Side effects:
+ *      Can allocate thread-specific data for handling the copy-out space for
+ *      bignums; this space is shared within a thread.
  *
  *----------------------------------------------------------------------
  */
@@ -3611,18 +3636,18 @@ TclGetNumberFromObj(
 	    } else {
 		*typePtr = TCL_NUMBER_DOUBLE;
 	    }
-	    *clientDataPtr = &(objPtr->internalRep.doubleValue);
+	    *clientDataPtr = &objPtr->internalRep.doubleValue;
 	    return TCL_OK;
 	}
 	if (objPtr->typePtr == &tclIntType) {
 	    *typePtr = TCL_NUMBER_LONG;
-	    *clientDataPtr = &(objPtr->internalRep.longValue);
+	    *clientDataPtr = &objPtr->internalRep.longValue;
 	    return TCL_OK;
 	}
 #ifndef NO_WIDE_TYPE
 	if (objPtr->typePtr == &tclWideIntType) {
 	    *typePtr = TCL_NUMBER_WIDE;
-	    *clientDataPtr = &(objPtr->internalRep.wideValue);
+	    *clientDataPtr = &objPtr->internalRep.wideValue;
 	    return TCL_OK;
 	}
 #endif
-- 
cgit v0.12