Improvements to v8::Value comments to make a little easier for new users to

include/v8.h

 // Copyright 2011 the V8 project authors. All rights reserved.
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 //       notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 //       copyright notice, this list of conditions and the following
 //       disclaimer in the documentation and/or other materials provided
@@ skipping 836 matching lines @@
    * constructor via "new".
    */
   bool IsConstructor() const;
 };
 
 
 // --- Value ---
 
 
 /**
- * The superclass of all JavaScript values and objects.
+ * The superclass of all JavaScript values.
+ *
+ * ECMA-262 defines six types, undefined, null, boolean, string, number and 
+ * object. The Value class provides a mechanism for accessing internal data 
+ * held in values of these types, it does not store the data but instead 
+ * operates as a Value reference or Value accessor.
+ *
+ * There are a number of built-in object types for functions, arrays, strings
+ * booleans, numbers, dates and regular expressions. Values of these types
+ * can also be accessed via this class. The value class also supports External
+ * and NativeError objects types which are outside ECMA-262 scope.
+ *
+ * Types are defined in secion 8 of ECMA-262, built in objects are described in
+ * section 15.
  */
 class Value : public Data {
  public:
   /**
-   * Returns true if this value is the undefined value.  See ECMA-262
-   * 4.3.10.
+   * Returns true if this value is of undefined type.  
+   * See ECMA-262 8.1 
    */
   V8EXPORT bool IsUndefined() const;
 
   /**
-   * Returns true if this value is the null value.  See ECMA-262
-   * 4.3.11.
+   * Returns true if this value is of null type.  
+   * See ECMA-262 8.2
    */
   V8EXPORT bool IsNull() const;
 
-   /**
-   * Returns true if this value is true.
+  /**
+   * Returns true if this value is boolean. This does not test for 
+   * Boolean objects, only values of boolean type.
+   * See ECMA-262 8.3
+   */
+  V8EXPORT bool IsBoolean() const;
+
+  /**
+   * Returns true if this value is of boolean type and is true. For a Boolean
+   * object value this will always return false.
    */
   V8EXPORT bool IsTrue() const;
 
   /**
-   * Returns true if this value is false.
+   * Returns true if this value is of boolean type and is false. For a Boolean
+   * object value this will always return false.
    */
   V8EXPORT bool IsFalse() const;
 
   /**
-   * Returns true if this value is an instance of the String type.
+   * Returns true if this value is of string type. For a String object value 
+   * this will always return false.
    * See ECMA-262 8.4.
    */
   inline bool IsString() const;
-
-  /**
-   * Returns true if this value is a function.
+  
+  /**
+   * Returns true if this value is of number type. For a Number object value 
+   * this will always return false.
+   * See ECMA-262 8.5.
+   */
+  V8EXPORT bool IsNumber() const;
+  
+  /**
+   * Returns true if this value is a object type.
+   * See ECMA-262 15.2
+   */
+  V8EXPORT bool IsObject() const;
+
+  /**
+   * Returns true if this value is a function object.
+   * See ECMA-262 15.3.
    */
   V8EXPORT bool IsFunction() const;
 
   /**
-   * Returns true if this value is an array.
+   * Returns true if this value is an array object.
+   * See ECMA-262 15.4.   
    */
   V8EXPORT bool IsArray() const;
-
-  /**
-   * Returns true if this value is an object.
-   */
-  V8EXPORT bool IsObject() const;
-
-  /**
-   * Returns true if this value is boolean.
-   */
-  V8EXPORT bool IsBoolean() const;
-
-  /**
-   * Returns true if this value is a number.
-   */
-  V8EXPORT bool IsNumber() const;
-
-  /**
-   * Returns true if this value is external.
+  
+  /**
+   * Returns true if this value is a String object.
+   * See ECMA-262 15.5.      
+   */
+  V8EXPORT bool IsStringObject() const;
+  
+  /**
+   * Returns true if this value is a Boolean object.
+   * See ECMA-262 15.6.      
+   */
+  V8EXPORT bool IsBooleanObject() const;
+  
+  /**
+   * Returns true if this value is a Number object.
+   * See ECMA-262 15.7.      
+   */
+  V8EXPORT bool IsNumberObject() const;
+  
+  /**
+   * Returns true if this value is a Date object.
+   * See ECMA-262 15.9.      
+   */
+  V8EXPORT bool IsDate() const;
+  
+  /**
+   * Returns true if this value is a regular expression object.
+   * See ECMA-262 15.10.      
+   */
+  V8EXPORT bool IsRegExp() const;
+ 
+  /**
+   * Returns true if this value is an external object.
    */
   V8EXPORT bool IsExternal() const;
-
-  /**
-   * Returns true if this value is a 32-bit signed integer.
+  
+  /**
+   * Returns true if this value is a NativeError object.
+   */
+  V8EXPORT bool IsNativeError() const;
+
+  /**
+   * Returns true if this value is either a number type or a Number object 
+   * and its value can be stored in a signed 32-bit integer without error.
    */
   V8EXPORT bool IsInt32() const;
 
   /**
-   * Returns true if this value is a 32-bit unsigned integer.
+   * Returns true if this value is either a number type or a Number object
+   * and its value can be stored in a unsigned 32-bit integer without error.
    */
   V8EXPORT bool IsUint32() const;
 
   /**
-   * Returns true if this value is a Date.
-   */
-  V8EXPORT bool IsDate() const;
-
-  /**
-   * Returns true if this value is a Boolean object.
-   */
-  V8EXPORT bool IsBooleanObject() const;
-
-  /**
-   * Returns true if this value is a Number object.
-   */
-  V8EXPORT bool IsNumberObject() const;
-
-  /**
-   * Returns true if this value is a String object.
-   */
-  V8EXPORT bool IsStringObject() const;
-
-  /**
-   * Returns true if this value is a NativeError.
-   */
-  V8EXPORT bool IsNativeError() const;
-
-  /**
-   * Returns true if this value is a RegExp.
-   */
-  V8EXPORT bool IsRegExp() const;
-
+   * These functions convert the value to a number according to ECAMA-262 9.1. 
+   * The result is either returned directly or as a value.
+   */
+  V8EXPORT Local<Number> ToNumber() const;
+  V8EXPORT double NumberValue() const;
+
+  /**
+   * These functions convert the value to a signed 64-bit integer by first 
+   * converting to a number according to ECAMA-262 9.3 and then converting that 
+   * number to an integer as per section 9.6. The result is either returned 
+   * directly or via an internally managed value.
+   */
+  V8EXPORT int64_t IntegerValue() const;
+  V8EXPORT Local<Integer> ToInteger() const;
+
+  /**
+   * These functions convert the value to a boolean according to ECAMA-262 9.1.
+   * The result is either returned directly or as an value.
+   */
   V8EXPORT Local<Boolean> ToBoolean() const;
-  V8EXPORT Local<Number> ToNumber() const;
+  V8EXPORT bool BooleanValue() const;
+
+  /**
+   * These functions convert the value to a unsigned 32-bit integer by first 
+   * converting to a number according to ECAMA-262 9.3 and then converting that
+   * number to an integer as per section 9.6. The result is either returned 
+   * directly or via an internally managed value.
+   */
+  V8EXPORT Local<Uint32> ToUint32() const;
+  V8EXPORT int32_t Int32Value() const;
+
+  /**
+   * These functions convert the value to a signed 32-bit integer by first 
+   * converting to a number according to ECAMA-262 9.3 and then converting that
+   * number to an integer as per section 9.5. The result is either returned 
+   * directly or via an internally managed value.
+   */
+  V8EXPORT Local<Int32> ToInt32() const;
+  V8EXPORT uint32_t Uint32Value() const;
+
+  /**
+   * This function converts the value to a String according to ECMA-262 9.8 and
+   * then if possible to a unsigned 32-bit value that could possibly be used 
+   * to access an array. It returns an empty handle if the value is not 
+   * suitable for use as an index.
+   */
+  V8EXPORT Local<Uint32> ToArrayIndex() const;
+
+  /**
+   * This functions convert the value to a string according to 
+   * ECMA-262 9.8.
+   */
   V8EXPORT Local<String> ToString() const;
+
+  /**
+   * This function returns a string for an object similarly to ToString() with
+   * the exceptions that for NativeError objects a formatted message is 
+   * returned. 
+   */
   V8EXPORT Local<String> ToDetailString() const;
+
+  /**
+   * This functions convert the value to an object according to ECAMA-262 9.9. 
+   * Undefined, Null and undetectable objects will result in a empty value 
+   * being returned.
+   */
   V8EXPORT Local<Object> ToObject() const;
-  V8EXPORT Local<Integer> ToInteger() const;
-  V8EXPORT Local<Uint32> ToUint32() const;
-  V8EXPORT Local<Int32> ToInt32() const;
-
-  /**
-   * Attempts to convert a string to an array index.
-   * Returns an empty handle if the conversion fails.
-   */
-  V8EXPORT Local<Uint32> ToArrayIndex() const;
-
-  V8EXPORT bool BooleanValue() const;
-  V8EXPORT double NumberValue() const;
-  V8EXPORT int64_t IntegerValue() const;
-  V8EXPORT uint32_t Uint32Value() const;
-  V8EXPORT int32_t Int32Value() const;
-
-  /** JS == */
+
+  /** 
+   * These functions compare values for equality according to ECMA-262 11.9.3 
+   * & 11.9.4.
+   */
   V8EXPORT bool Equals(Handle<Value> that) const;
   V8EXPORT bool StrictEquals(Handle<Value> that) const;
 
  private:
   inline bool QuickIsString() const;
   V8EXPORT bool FullIsString() const;
 };
 
 
 /**
@@ skipping 3285 matching lines @@
 
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_