Reviewed by Geoff.
authormjs <mjs@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Thu, 29 Jun 2006 23:32:47 +0000 (23:32 +0000)
committermjs <mjs@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Thu, 29 Jun 2006 23:32:47 +0000 (23:32 +0000)
        - add headerdoc comments to some of the new JS API headers

        * API/JSBase.h:
        * API/JSValueRef.h:

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@15096 268f45cc-cd09-0410-ab3c-d52691b4dbfc

JavaScriptCore/API/JSBase.h
JavaScriptCore/API/JSValueRef.h
JavaScriptCore/ChangeLog

index 794da83c8dcc067467471a8a782e7f8a8a39fb6a..7d79efea33cf2374f1648e1428fcf992247174b6 100644 (file)
@@ -44,12 +44,55 @@ extern "C" {
 
 // Returns true for successful execution, false for uncaught exception. 
 // returnValue will contain value of last evaluated statement or exception value.
 
 // Returns true for successful execution, false for uncaught exception. 
 // returnValue will contain value of last evaluated statement or exception value.
+/*!
+  @function JSEvaluate
+  Evaluates a string of JavaScript code
+  @param context            execution context to use
+  @param thisValue          object to use as the "this" value, or NULL to use the global object as "this"
+  @param script             a string containing the script source code
+  @param sourceURL          URL to the file containing the source, or NULL - this is only used for error reporting
+  @param startingLineNumber starting line number in the source at sourceURL - this is only used for error reporting
+  @param returnValue        result of evaluation if successful, or value of exception
+  @result                   true if evaluation succeeded, false if an uncaught exception or error occured
+*/
 bool JSEvaluate(JSContextRef context, JSValueRef thisValue, JSCharBufferRef script, JSCharBufferRef sourceURL, int startingLineNumber, JSValueRef* returnValue);
 bool JSEvaluate(JSContextRef context, JSValueRef thisValue, JSCharBufferRef script, JSCharBufferRef sourceURL, int startingLineNumber, JSValueRef* returnValue);
+
+/*!
+  @function JSCheckSyntax
+  Checks for syntax errors in a string of JavaScript code
+  @param context execution context to use
+  @param script a string containing the script source code
+  @result true if the script is syntactically correct, false otherwise
+
+*/
 bool JSCheckSyntax(JSContextRef context, JSCharBufferRef script);
 
 // Garbage collection
 bool JSCheckSyntax(JSContextRef context, JSCharBufferRef script);
 
 // Garbage collection
+/*!
+  @function JSGCProtect
+  Protect a JavaScript value from garbage collection; a value may be
+  protected multiple times and must be unprotected an equal number of
+  times to become collectable again.
+*/
 void JSGCProtect(JSValueRef value);
 void JSGCProtect(JSValueRef value);
+
+/*!
+  @function JSGCProtect
+  Stop protecting a JavaScript value from garbage collection; a value may be
+  protected multiple times and must be unprotected an equal number of
+  times to become collectable again.
+*/
 void JSGCUnprotect(JSValueRef value);
 void JSGCUnprotect(JSValueRef value);
+
+/*! 
+  @function JSGCCollect
+  Immediately perform a JavaScript garbage collection. JavaScript
+  values that are on the machine stack, in a register, protected, set
+  as the global object of any interpreter, or reachable from any such
+  value will not be collected. It is not normally necessary to call
+  this function directly; the JS runtime will garbage collect as
+  needed.
+*/
 void JSGCCollect(void);
 
 #ifdef __cplusplus
 void JSGCCollect(void);
 
 #ifdef __cplusplus
index 8ef1e6adcce0b5a5e61f5664f79ee57ccbae579f..a823327d0b354c432d7f6800911d0586296caa78 100644 (file)
 
 #include "JSBase.h"
 
 
 #include "JSBase.h"
 
-// Value types
+/*!
+  @enum JSTypeCode
+  A constant identifying the type of a particular JSValueRef.
+  @constant kJSTypeUndefined the unique undefined value
+  @constant kJSTypeNull the unique null value
+  @constant kJSBoolean a primitive boolean value, one of true or false
+  @constant kJSTypeNumber a primitive number value
+  @constant kJSTypeString a primitive string value
+  @constant kJSTypeObject an object (meaning this JSValueRef is a JSObjectRef
+*/
 typedef enum {
     kJSTypeUndefined,
     kJSTypeNull,
 typedef enum {
     kJSTypeUndefined,
     kJSTypeNull,
@@ -43,32 +52,173 @@ typedef enum {
 extern "C" {
 #endif
 
 extern "C" {
 #endif
 
+/*!
+  @function JSValueGetType
+  Get the type code for a particular JavaScript value
+  @param value the JS value for which the type should be determined
+  @result      a type code identifying the type
+*/
 JSTypeCode JSValueGetType(JSValueRef value);
 
 JSTypeCode JSValueGetType(JSValueRef value);
 
+/*!
+  @function JSValueIsUndefined
+  Determine if value is of type undefined
+  @param value the JS value to check for undefined type
+  @result      true if the value is undefined, false otherwise
+*/
 bool JSValueIsUndefined(JSValueRef value);
 bool JSValueIsUndefined(JSValueRef value);
+
+/*!
+  @function JSValueIsNull
+  Determine if value is of type null
+  @param value the JS value to check for null type
+  @result      true if the value is null, false otherwise
+*/
 bool JSValueIsNull(JSValueRef value);
 bool JSValueIsNull(JSValueRef value);
+
+/*!
+  @function JSValueIsBoolean
+  Determine if value is of type boolean
+  @param value the JS value to check for boolean type
+  @result      true if the value is a boolean, false otherwise
+*/
 bool JSValueIsBoolean(JSValueRef value);
 bool JSValueIsBoolean(JSValueRef value);
+
+/*!
+  @function JSValueIsNumber
+  Determine if value is of type number
+  @param value the JS value to check for number type
+  @result      true if the value is a number, false otherwise
+*/
 bool JSValueIsNumber(JSValueRef value);
 bool JSValueIsNumber(JSValueRef value);
+
+/*!
+  @function JSValueIsString
+  Determine if value is of type string
+  @param value the JS value to check for string type
+  @result      true if the value is a string, false otherwise
+*/
 bool JSValueIsString(JSValueRef value);
 bool JSValueIsString(JSValueRef value);
+
+/*!
+  @function JSValueIsObject
+  Determine if value is of type object
+  @param value the JS value to check for object type
+  @result      true if the value is an object, false otherwise
+*/
 bool JSValueIsObject(JSValueRef value);
 
 // Comparing values
 bool JSValueIsObject(JSValueRef value);
 
 // Comparing values
+
+/*!
+  @function JSValueIsEqual
+  Check if two values are equal by JavaScript rules, as if compared by the JS == operator
+  @param context the execution context to use 
+  @param a       the first value to compare
+  @param b       the second value to compare
+  @result        true if the two values are equal, false otherwise
+*/
 bool JSValueIsEqual(JSContextRef context, JSValueRef a, JSValueRef b);
 bool JSValueIsEqual(JSContextRef context, JSValueRef a, JSValueRef b);
+
+/*!
+  @function JSValueIsStrictEqual
+  Check if two values are strict equal by JavaScript rules, as if compared by the JS === operator
+  @param context the execution context to use 
+  @param a       the first value to compare
+  @param b       the second value to compare
+  @result        true if the two values are strict equal, false otherwise
+*/
 bool JSValueIsStrictEqual(JSContextRef context, JSValueRef a, JSValueRef b);
 bool JSValueIsStrictEqual(JSContextRef context, JSValueRef a, JSValueRef b);
+
+/*!
+  @function JSValueIsInstanceOf
+  Check if a value is an instance of a particular object; generally this means the object
+  was used as the constructor for that instance
+  @param context the execution context to use 
+  @param value   the possible instance
+  @param object  the possible constructor
+  @result        true if value is an instance of object
+*/
 bool JSValueIsInstanceOf(JSValueRef value, JSObjectRef object);
 
 // Creating values
 bool JSValueIsInstanceOf(JSValueRef value, JSObjectRef object);
 
 // Creating values
+
+/*!
+  @function JSUndefinedMake
+  Make a value of the undefined type.
+  @result The unique undefined value.
+*/
 JSValueRef JSUndefinedMake(void);
 JSValueRef JSUndefinedMake(void);
+
+/*!
+  @function JSNullMake
+  Make a value of the null type.
+  @result the unique null value
+*/
 JSValueRef JSNullMake(void);
 JSValueRef JSNullMake(void);
+
+/*!
+  @function JSBooleanMake
+  Make a value of the boolean type.
+  @param value whether the returned value should be true or false
+  @result      a JS true or false boolean value, as appropriate
+*/
+
 JSValueRef JSBooleanMake(bool value);
 JSValueRef JSBooleanMake(bool value);
+
+/*!
+  @function JSNumberMake
+  Make a value of the number type.
+  @param  value the numberic value of the number to make
+  @result a JS number corresponding to value
+*/
 JSValueRef JSNumberMake(double value);
 JSValueRef JSNumberMake(double value);
+
+/*!
+  @function JSStringMake
+  Make a value of the string type.
+  @param  buffer the internal string contents for the string value
+  @result a JS string value that has the value of the buffer
+*/
 JSValueRef JSStringMake(JSCharBufferRef buffer);
 
 // Converting to primitive values
 JSValueRef JSStringMake(JSCharBufferRef buffer);
 
 // Converting to primitive values
+
+/*!
+  @function JSValueToBoolean
+  Convert a JavaScript value to boolean and get the boolean value
+  @param context the execution context to use 
+  @param value   the value to convert to boolean
+  @result        the boolean result of conversion
+*/
 bool JSValueToBoolean(JSContextRef context, JSValueRef value);
 bool JSValueToBoolean(JSContextRef context, JSValueRef value);
-double JSValueToNumber(JSContextRef context, JSValueRef value); // 0.0 if conversion fails
-JSObjectRef JSValueToObject(JSContextRef context, JSValueRef value); // Error object if conversion fails
-JSCharBufferRef JSValueCopyStringValue(JSContextRef context, JSValueRef value); // Empty string if conversion fails
+
+/*!
+  @function JSValueToNumber
+  Convert a JavaScript value to number and get the numeric value
+  @param context the execution context to use 
+  @param value   the value to convert to number
+  @result        the boolean result of conversion, or 0 on failure
+*/
+double JSValueToNumber(JSContextRef context, JSValueRef value);
+
+/*!
+  @function JSValueCopyStringValue
+  Convert a JavaScript value to string and get the value as a string
+  @param context the execution context to use 
+  @param value   the value to convert to string
+  @result        the string result of conversion, or empty string on failure
+*/
+JSCharBufferRef JSValueCopyStringValue(JSContextRef context, JSValueRef value);
+
+/*!
+  @function JSValueToObject
+  Convert a JavaScript value to object and return the resulting object
+  @param context the execution context to use 
+  @param value   the value to convert to string
+  @result        the string result of conversion, or error object on failure
+*/
+JSObjectRef JSValueToObject(JSContextRef context, JSValueRef value);
 
 #ifdef __cplusplus
 }
 
 #ifdef __cplusplus
 }
index 6dd5d1abc9860e0b6a23c153f1187732e54ccf90..efab68393c2c13883d27e5a15dc19dbd513ff424 100644 (file)
@@ -1,3 +1,12 @@
+2006-06-29  Maciej Stachowiak  <mjs@apple.com>
+
+        Reviewed by Geoff.
+        
+        - add headerdoc comments to some of the new JS API headers
+
+        * API/JSBase.h:
+        * API/JSValueRef.h:
+
 2006-06-28  Timothy Hatcher  <timothy@apple.com>
 
         Prefer the Stabs debugging symbols format until DWARF bugs are fixed.
 2006-06-28  Timothy Hatcher  <timothy@apple.com>
 
         Prefer the Stabs debugging symbols format until DWARF bugs are fixed.