<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[159723] trunk/Source/JavaScriptCore</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://trac.webkit.org/projects/webkit/changeset/159723">159723</a></dd>
<dt>Author</dt> <dd>mhahnenberg@apple.com</dd>
<dt>Date</dt> <dd>2013-11-22 18:54:31 -0800 (Fri, 22 Nov 2013)</dd>
</dl>
<h3>Log Message</h3>
<pre>JSC Obj-C API should have real documentation
https://bugs.webkit.org/show_bug.cgi?id=124805
Reviewed by Geoffrey Garen.
Massaging the header comments into proper headerdocs.
* API/JSContext.h:
* API/JSExport.h:
* API/JSManagedValue.h:
* API/JSValue.h:
* API/JSVirtualMachine.h:</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkSourceJavaScriptCoreAPIJSContexth">trunk/Source/JavaScriptCore/API/JSContext.h</a></li>
<li><a href="#trunkSourceJavaScriptCoreAPIJSExporth">trunk/Source/JavaScriptCore/API/JSExport.h</a></li>
<li><a href="#trunkSourceJavaScriptCoreAPIJSManagedValueh">trunk/Source/JavaScriptCore/API/JSManagedValue.h</a></li>
<li><a href="#trunkSourceJavaScriptCoreAPIJSValueh">trunk/Source/JavaScriptCore/API/JSValue.h</a></li>
<li><a href="#trunkSourceJavaScriptCoreAPIJSVirtualMachineh">trunk/Source/JavaScriptCore/API/JSVirtualMachine.h</a></li>
<li><a href="#trunkSourceJavaScriptCoreChangeLog">trunk/Source/JavaScriptCore/ChangeLog</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkSourceJavaScriptCoreAPIJSContexth"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/API/JSContext.h (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/API/JSContext.h 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/API/JSContext.h 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -32,15 +32,17 @@
</span><span class="cx">
</span><span class="cx"> @class JSVirtualMachine, JSValue;
</span><span class="cx">
</span><del>-// An instance of JSContext represents a JavaScript execution environment. All
-// JavaScript execution takes place within a context.
-// JSContext is also used to manage the life-cycle of objects within the
-// JavaScript virtual machine. Every instance of JSValue is associated with a
-// JSContext via a strong reference. The JSValue will keep the JSContext it
-// references alive so long as the JSValue remains alive. When all of the JSValues
-// that reference a particular JSContext have been deallocated the JSContext
-// will be deallocated unless it has been previously retained.
-
</del><ins>+/*!
+@interface
+@discussion An instance of JSContext represents a JavaScript execution environment. All
+ JavaScript execution takes place within a context.
+ JSContext is also used to manage the life-cycle of objects within the
+ JavaScript virtual machine. Every instance of JSValue is associated with a
+ JSContext via a strong reference. The JSValue will keep the JSContext it
+ references alive so long as the JSValue remains alive. When all of the JSValues
+ that reference a particular JSContext have been deallocated the JSContext
+ will be deallocated unless it has been previously retained.
+*/
</ins><span class="cx"> #ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
</span><span class="cx"> NS_CLASS_AVAILABLE(10_9, 7_0)
</span><span class="cx"> #else
</span><span class="lines">@@ -48,83 +50,176 @@
</span><span class="cx"> #endif
</span><span class="cx"> @interface JSContext : NSObject
</span><span class="cx">
</span><del>-// Create a JSContext.
</del><ins>+/*!
+@methodgroup Creating New JSContexts
+*/
+/*!
+@method
+@abstract Create a JSContext.
+@result The new context.
+*/
</ins><span class="cx"> - (id)init;
</span><del>-// Create a JSContext in the specified virtual machine.
</del><ins>+
+/*!
+@method
+@abstract Create a JSContext in the specified virtual machine.
+@param virtualMachine The JSVirtualMachine in which the context will be created.
+@result The new context.
+*/
</ins><span class="cx"> - (id)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
</span><span class="cx">
</span><del>-// Evaluate a string of JavaScript code.
</del><ins>+/*!
+@methodgroup Evaluating Scripts
+*/
+/*!
+@method
+@abstract Evaluate a string of JavaScript code.
+@param script A string containing the JavaScript code to evaluate.
+@result The last value generated by the script.
+*/
</ins><span class="cx"> - (JSValue *)evaluateScript:(NSString *)script;
</span><span class="cx">
</span><del>-// This method retrieves the global object of the JavaScript execution context.
-// Instances of JSContext originating from WebKit will return a reference to the
-// WindowProxy object.
-- (JSValue *)globalObject;
</del><ins>+/*!
+@methodgroup Callback Accessors
+*/
+/*!
+@method
+@abstract Get the JSContext that is currently executing.
+@discussion This method may be called from within an Objective-C block or method invoked
+ as a callback from JavaScript to retrieve the callback's context. Outside of
+ a callback from JavaScript this method will return nil.
+@result The currently executing JSContext or nil if there isn't one.
+*/
++ (JSContext *)currentContext;
</ins><span class="cx">
</span><del>-// This method may be called from within an Objective-C block or method invoked
-// as a callback from JavaScript to retrieve the callback's context. Outside of
-// a callback from JavaScript this method will return nil.
-+ (JSContext *)currentContext;
-// This method may be called from within an Objective-C block or method invoked
-// as a callback from JavaScript to retrieve the callback's this value. Outside
-// of a callback from JavaScript this method will return nil.
</del><ins>+/*!
+@method
+@abstract Get the <code>this</code> value of the currently executing method.
+@discussion This method may be called from within an Objective-C block or method invoked
+ as a callback from JavaScript to retrieve the callback's this value. Outside
+ of a callback from JavaScript this method will return nil.
+@result The current <code>this</code> value or nil if there isn't one.
+*/
</ins><span class="cx"> + (JSValue *)currentThis;
</span><del>-// This method may be called from within an Objective-C block or method invoked
-// as a callback from JavaScript to retrieve the callback's arguments, objects
-// in the returned array are instances of JSValue. Outside of a callback from
-// JavaScript this method will return nil.
</del><ins>+
+/*!
+@method
+@abstract Get the arguments to the current callback.
+@discussion This method may be called from within an Objective-C block or method invoked
+ as a callback from JavaScript to retrieve the callback's arguments, objects
+ in the returned array are instances of JSValue. Outside of a callback from
+ JavaScript this method will return nil.
+@result An NSArray of the arguments nil if there is no current callback.
+*/
</ins><span class="cx"> + (NSArray *)currentArguments;
</span><span class="cx">
</span><del>-// The "exception" property may be used to throw an exception to JavaScript.
-// Before a callback is made from JavaScript to an Objective-C block or method,
-// the prior value of the exception property will be preserved and the property
-// will be set to nil. After the callback has completed the new value of the
-// exception property will be read, and prior value restored. If the new value
-// of exception is not nil, the callback will result in that value being thrown.
-// This property may also be used to check for uncaught exceptions arising from
-// API function calls (since the default behaviour of "exceptionHandler" is to
-// assign an uncaught exception to this property).
-// If a JSValue originating from a different JSVirtualMachine than this context
-// is assigned to this property, an Objective-C exception will be raised.
</del><ins>+/*!
+@methodgroup Global Properties
+*/
+/*!
+@method
+@abstract Get the global object of the context.
+@discussion This method retrieves the global object of the JavaScript execution context.
+ Instances of JSContext originating from WebKit will return a reference to the
+ WindowProxy object.
+@result The global object.
+*/
+- (JSValue *)globalObject;
+
+/*!
+@property
+@discussion The <code>exception</code> property may be used to throw an exception to JavaScript.
+
+ Before a callback is made from JavaScript to an Objective-C block or method,
+ the prior value of the exception property will be preserved and the property
+ will be set to nil. After the callback has completed the new value of the
+ exception property will be read, and prior value restored. If the new value
+ of exception is not nil, the callback will result in that value being thrown.
+
+ This property may also be used to check for uncaught exceptions arising from
+ API function calls (since the default behaviour of <code>exceptionHandler</code> is to
+ assign an uncaught exception to this property).
+
+ If a JSValue originating from a different JSVirtualMachine than this context
+ is assigned to this property, an Objective-C exception will be raised.
+*/
</ins><span class="cx"> @property(retain) JSValue *exception;
</span><span class="cx">
</span><del>-// If a call to an API function results in an uncaught JavaScript exception, the
-// "exceptionHandler" block will be invoked. The default implementation for the
-// exception handler will store the exception to the exception property on
-// context. As a consequence the default behaviour is for unhandled exceptions
-// occurring within a callback from JavaScript to be rethrown upon return.
-// Setting this value to nil will result in all uncaught exceptions thrown from
-// the API being silently consumed.
</del><ins>+/*!
+@property
+@discussion If a call to an API function results in an uncaught JavaScript exception, the
+ <code>exceptionHandler</code> block will be invoked. The default implementation for the
+ exception handler will store the exception to the exception property on
+ context. As a consequence the default behaviour is for unhandled exceptions
+ occurring within a callback from JavaScript to be rethrown upon return.
+ Setting this value to nil will result in all uncaught exceptions thrown from
+ the API being silently consumed.
+*/
</ins><span class="cx"> @property(copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
</span><span class="cx">
</span><del>-// All instances of JSContext are associated with a single JSVirtualMachine. The
-// virtual machine provides an "object space" or set of execution resources.
</del><ins>+/*!
+@property
+@discussion All instances of JSContext are associated with a single JSVirtualMachine. The
+ virtual machine provides an "object space" or set of execution resources.
+*/
</ins><span class="cx"> @property(readonly, retain) JSVirtualMachine *virtualMachine;
</span><span class="cx">
</span><span class="cx"> @end
</span><span class="cx">
</span><del>-// Instances of JSContext implement the following methods in order to enable
-// support for subscript access by key and index, for example:
-//
-// JSContext *context;
-// JSValue *v = context[@"X"]; // Get value for "X" from the global object.
-// context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
-//
-// An object key passed as a subscript will be converted to a JavaScript value,
-// and then the value converted to a string used to resolve a property of the
-// global object.
</del><ins>+/*!
+@category
+@discussion Instances of JSContext implement the following methods in order to enable
+ support for subscript access by key and index, for example:
+
+@textblock
+ JSContext *context;
+ JSValue *v = context[@"X"]; // Get value for "X" from the global object.
+ context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
+@/textblock
+
+ An object key passed as a subscript will be converted to a JavaScript value,
+ and then the value converted to a string used to resolve a property of the
+ global object.
+*/
</ins><span class="cx"> @interface JSContext(SubscriptSupport)
</span><span class="cx">
</span><ins>+/*!
+method
+@abstract Get a particular property on the global object.
+@param key
+@result The JSValue for the global object's property.
+*/
</ins><span class="cx"> - (JSValue *)objectForKeyedSubscript:(id)key;
</span><ins>+
+/*!
+method
+@abstract Set a particular property on the global object.
+@param object
+@param key
+*/
</ins><span class="cx"> - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
</span><span class="cx">
</span><span class="cx"> @end
</span><span class="cx">
</span><del>-// These functions are for bridging between the C API and the Objective-C API.
</del><ins>+/*!
+@category
+@discussion These functions are for bridging between the C API and the Objective-C API.
+*/
</ins><span class="cx"> @interface JSContext(JSContextRefSupport)
</span><del>-// Creates a JSContext, wrapping its C API counterpart.
</del><ins>+
+/*!
+@method
+@abstract Create a JSContext, wrapping its C API counterpart.
+@param jsGlobalContextRef
+@result The JSContext equivalent of the provided JSGlobalContextRef.
+*/
</ins><span class="cx"> + (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
</span><del>-// Returns the C API counterpart wrapped by a JSContext.
</del><ins>+
+/*!
+@method
+@abstract Get the C API counterpart wrapped by a JSContext.
+@result The C API equivalent of this JSContext.
+*/
</ins><span class="cx"> - (JSGlobalContextRef)JSGlobalContextRef;
</span><span class="cx"> @end
</span><span class="cx">
</span></span></pre></div>
<a id="trunkSourceJavaScriptCoreAPIJSExporth"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/API/JSExport.h (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/API/JSExport.h 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/API/JSExport.h 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -27,103 +27,125 @@
</span><span class="cx">
</span><span class="cx"> #if JSC_OBJC_API_ENABLED
</span><span class="cx">
</span><del>-// When a JavaScript value is created from an instance of an Objective-C class
-// for which no copying conversion is specified a JavaScript wrapper object will
-// be created.
-//
-// In JavaScript inheritance is supported via a chain of prototype objects, and
-// for each Objective-C class (and per JSContext) an object appropriate for use
-// as a prototype will be provided. For the class NSObject the prototype object
-// will be the JavaScript context's Object Prototype. For all other Objective-C
-// classes a Prototype object will be created. The Prototype object for a given
-// Objective-C class will have its internal [Prototype] property set to point to
-// the Prototype object of the Objective-C class's superclass. As such the
-// prototype chain for a JavaScript wrapper object will reflect the wrapped
-// Objective-C type's inheritance hierarchy.
-//
-// In addition to the Prototype object a JavaScript Constructor object will also
-// be produced for each Objective-C class. The Constructor object has a property
-// named 'prototype' that references the Prototype object, and the Prototype
-// object has a property named 'constructor' that references the Constructor.
-// The Constructor object is not callable.
-//
-// By default no methods or properties of the Objective-C class will be exposed
-// to JavaScript, however methods and properties may explicitly be exported.
-// For each protocol that a class conforms to, if the protocol incorporates the
-// protocol JSExport, then the protocol will be interpreted as a list of methods
-// and properties to be exported to JavaScript.
-//
-// For each instance method being exported, a corresponding JavaScript function
-// will be assigned as a property of the Prototype object, for each Objective-C
-// property being exported a JavaScript accessor property will be created on the
-// Prototype, and for each class method exported a JavaScript function will be
-// created on the Constructor object. For example:
-//
-// @protocol MyClassJavaScriptMethods <JSExport>
-// - (void)foo;
-// @end
-//
-// @interface MyClass : NSObject <MyClassJavaScriptMethods>
-// - (void)foo;
-// - (void)bar;
-// @end
-//
-// Data properties that are created on the prototype or constructor objects have
-// the attributes: writable:true, enumerable:false, configurable:true. Accessor
-// properties have the attributes: enumerable:false and configurable:true.
-//
-// If an instance of MyClass is converted to a JavaScript value, the resulting
-// wrapper object will (via its prototype) export the method "foo" to JavaScript,
-// since the class conforms to the MyClassJavaScriptMethods protocol, and this
-// protocol incorporates JSExport. "bar" will not be exported.
-//
-// Properties, arguments, and return values of the following types are
-// supported:
-//
-// Primitive numbers: signed values of up to 32-bits are converted in a manner
-// consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits
-// are converted in a manner consistent with valueWithUInt32/toUInt32, all
-// other numeric values are converted consistently with valueWithDouble/
-// toDouble.
-// BOOL: values are converted consistently with valueWithBool/toBool.
-// id: values are converted consistently with valueWithObject/toObject.
-// <Objective-C Class>: - where the type is a pointer to a specified Objective-C
-// class, conversion is consistent with valueWithObjectOfClass/toObject.
-// struct types: C struct types are supported, where JSValue provides support
-// for the given type. Support is built in for CGPoint, NSRange, CGRect, and
-// CGSize.
-// block types: In addition to support provided by valueWithObject/toObject for
-// block types, if a JavaScript Function is passed as an argument, where the
-// type required is a block with a void return value (and where the block's
-// arguments are all of supported types), then a special adaptor block
-// will be created, allowing the JavaScript function to be used in the place
-// of a block.
-//
-// For any interface that conforms to JSExport the normal copying conversion for
-// built in types will be inhibited - so, for example, if an instance that
-// derives from NSString but conforms to JSExport is passed to valueWithObject:
-// then a wrapper object for the Objective-C object will be returned rather than
-// a JavaScript string primitive.
</del><ins>+/*!
+@protocol
+@abstract JSExport provides a declarative way to export Objective-C instance methods,
+ class methods, and properties to JavaScript code.
+
+@discussion When a JavaScript value is created from an instance of an Objective-C class
+ for which no copying conversion is specified a JavaScript wrapper object will
+ be created.
+
+ In JavaScript, inheritance is supported via a chain of prototype objects, and
+ for each Objective-C class (and per JSContext) an object appropriate for use
+ as a prototype will be provided. For the class NSObject the prototype object
+ will be the JavaScript context's Object Prototype. For all other Objective-C
+ classes a Prototype object will be created. The Prototype object for a given
+ Objective-C class will have its internal [Prototype] property set to point to
+ the Prototype object of the Objective-C class's superclass. As such the
+ prototype chain for a JavaScript wrapper object will reflect the wrapped
+ Objective-C type's inheritance hierarchy.
+
+ In addition to the Prototype object a JavaScript Constructor object will also
+ be produced for each Objective-C class. The Constructor object has a property
+ named 'prototype' that references the Prototype object, and the Prototype
+ object has a property named 'constructor' that references the Constructor.
+ The Constructor object is not callable.
+
+ By default no methods or properties of the Objective-C class will be exposed
+ to JavaScript; however methods and properties may explicitly be exported.
+ For each protocol that a class conforms to, if the protocol incorporates the
+ protocol JSExport, then the protocol will be interpreted as a list of methods
+ and properties to be exported to JavaScript.
+
+ For each instance method being exported a corresponding JavaScript function
+ will be assigned as a property of the Prototype object. For each Objective-C
+ property being exported a JavaScript accessor property will be created on the
+ Prototype. For each class method exported a JavaScript function will be
+ created on the Constructor object. For example:
+
+<pre>
+@textblock
+ @protocol MyClassJavaScriptMethods <JSExport>
+ - (void)foo;
+ @end
+
+ @interface MyClass : NSObject <MyClassJavaScriptMethods>
+ - (void)foo;
+ - (void)bar;
+ @end
+@/textblock
+</pre>
+
+ Data properties that are created on the prototype or constructor objects have
+ the attributes: <code>writable:true</code>, <code>enumerable:false</code>, <code>configurable:true</code>.
+ Accessor properties have the attributes: <code>enumerable:false</code> and <code>configurable:true</code>.
+
+ If an instance of <code>MyClass</code> is converted to a JavaScript value, the resulting
+ wrapper object will (via its prototype) export the method <code>foo</code> to JavaScript,
+ since the class conforms to the <code>MyClassJavaScriptMethods</code> protocol, and this
+ protocol incorporates <code>JSExport</code>. <code>bar</code> will not be exported.
+
+ Properties, arguments, and return values of the following types are
+ supported:
+
+ Primitive numbers: signed values of up to 32-bits are converted in a manner
+ consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits
+ are converted in a manner consistent with valueWithUInt32/toUInt32, all
+ other numeric values are converted consistently with valueWithDouble/
+ toDouble.
+
+ BOOL: values are converted consistently with valueWithBool/toBool.
+
+ id: values are converted consistently with valueWithObject/toObject.
+
+ Objective-C Class: - where the type is a pointer to a specified Objective-C
+ class, conversion is consistent with valueWithObjectOfClass/toObject.
+
+ struct types: C struct types are supported, where JSValue provides support
+ for the given type. Support is built in for CGPoint, NSRange, CGRect, and
+ CGSize.
+
+ block types: Blocks can only be passed if they had been converted
+ successfully by valueWithObject/toObject previously.
+
+ For any interface that conforms to JSExport the normal copying conversion for
+ built in types will be inhibited - so, for example, if an instance that
+ derives from NSString but conforms to JSExport is passed to valueWithObject:
+ then a wrapper object for the Objective-C object will be returned rather than
+ a JavaScript string primitive.
+*/
</ins><span class="cx"> @protocol JSExport
</span><span class="cx"> @end
</span><span class="cx">
</span><del>-// When a selector that takes one or more arguments is converted to a JavaScript
-// property name, by default a property name will be generated by performing the
-// following conversion:
-// - All colons are removed from the selector
-// - Any lowercase letter that had followed a colon will be capitalized.
-// Under the default conversion a selector "doFoo:withBar:" will be exported as
-// "doFooWithBar". The default conversion may be overriden using the JSExportAs
-// macro, for example to export a method "doFoo:withBar:" as "doFoo":
-//
-// @protocol MyClassJavaScriptMethods <JSExport>
-// JSExportAs(doFoo,
-// - (void)doFoo:(id)foo withBar:(id)bar
-// );
-// @end
-//
-// Note that the JSExport macro may only be applied to a selector that takes one
-// or more argument.
</del><ins>+/*!
+@define
+@abstract Rename a selector when it's exported to JavaScript.
+@discussion When a selector that takes one or more arguments is converted to a JavaScript
+ property name, by default a property name will be generated by performing the
+ following conversion:
+
+ - All colons are removed from the selector
+
+ - Any lowercase letter that had followed a colon will be capitalized.
+
+ Under the default conversion a selector <code>doFoo:withBar:</code> will be exported as
+ <code>doFooWithBar</code>. The default conversion may be overriden using the JSExportAs
+ macro, for example to export a method <code>doFoo:withBar:</code> as <code>doFoo</code>:
+
+<pre>
+@textblock
+ @protocol MyClassJavaScriptMethods <JSExport>
+ JSExportAs(doFoo,
+ - (void)doFoo:(id)foo withBar:(id)bar
+ );
+ @end
+@/textblock
+</pre>
+
+ Note that the JSExport macro may only be applied to a selector that takes one
+ or more argument.
+*/
</ins><span class="cx"> #define JSExportAs(PropertyName, Selector) \
</span><span class="cx"> @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector
</span><span class="cx">
</span></span></pre></div>
<a id="trunkSourceJavaScriptCoreAPIJSManagedValueh"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/API/JSManagedValue.h (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/API/JSManagedValue.h 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/API/JSManagedValue.h 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -33,19 +33,22 @@
</span><span class="cx"> @class JSValue;
</span><span class="cx"> @class JSContext;
</span><span class="cx">
</span><del>-// JSManagedValue represents a "conditionally retained" JSValue.
-// "Conditionally retained" means that as long as either the JSManagedValue
-// JavaScript value is reachable through the JavaScript object graph
-// or the JSManagedValue object is reachable through the external Objective-C
-// object graph as reported to the JSVirtualMachine using
-// addManagedReference:withOwner:, the corresponding JavaScript value will
-// be retained. However, if neither of these conditions are true, the
-// corresponding JSValue will be released and set to nil.
-//
-// The primary use case for JSManagedValue is for safely referencing JSValues
-// from the Objective-C heap. It is incorrect to store a JSValue into an
-// Objective-C heap object, as this can very easily create a reference cycle,
-// keeping the entire JSContext alive.
</del><ins>+/*!
+@interface
+@discussion JSManagedValue represents a "conditionally retained" JSValue.
+ "Conditionally retained" means that as long as either the JSManagedValue's
+ JavaScript value is reachable through the JavaScript object graph
+ or the JSManagedValue object is reachable through the external Objective-C
+ object graph as reported to the JSVirtualMachine using
+ addManagedReference:withOwner:, the corresponding JavaScript value will
+ be retained. However, if neither of these conditions are true, the
+ corresponding JSValue will be released and set to nil.
+
+ The primary use case for JSManagedValue is for safely referencing JSValues
+ from the Objective-C heap. It is incorrect to store a JSValue into an
+ Objective-C heap object, as this can very easily create a reference cycle,
+ keeping the entire JSContext alive.
+*/
</ins><span class="cx"> #ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
</span><span class="cx"> NS_CLASS_AVAILABLE(10_9, 7_0)
</span><span class="cx"> #else
</span><span class="lines">@@ -53,14 +56,28 @@
</span><span class="cx"> #endif
</span><span class="cx"> @interface JSManagedValue : NSObject
</span><span class="cx">
</span><del>-// Convenience method for creating JSManagedValues from JSValues.
</del><ins>+/*!
+@method
+@abstract Create a JSManagedValue from a JSValue.
+@param value
+@result The new JSManagedValue.
+*/
</ins><span class="cx"> + (JSManagedValue *)managedValueWithValue:(JSValue *)value;
</span><span class="cx">
</span><del>-// Create a JSManagedValue.
</del><ins>+/*!
+@method
+@abstract Create a JSManagedValue.
+@param value
+@result The new JSManagedValue.
+*/
</ins><span class="cx"> - (id)initWithValue:(JSValue *)value;
</span><span class="cx">
</span><del>-// Get the JSValue to which this JSManagedValue refers. If the JavaScript value has been collected,
-// this method returns nil.
</del><ins>+/*!
+@method
+@abstract Get the JSValue from the JSManagedValue.
+@result The corresponding JSValue for this JSManagedValue or
+ nil if the JSValue has been collected.
+*/
</ins><span class="cx"> - (JSValue *)value;
</span><span class="cx">
</span><span class="cx"> @end
</span></span></pre></div>
<a id="trunkSourceJavaScriptCoreAPIJSValueh"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/API/JSValue.h (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/API/JSValue.h 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/API/JSValue.h 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -32,63 +32,24 @@
</span><span class="cx">
</span><span class="cx"> @class JSContext;
</span><span class="cx">
</span><del>-// A JSValue is a reference to a value within the JavaScript object space of a
-// JSVirtualMachine. All instances of JSValue originate from a JSContext and
-// hold a strong reference to this JSContext. As long as any value associated with
-// a particular JSContext is retained, that JSContext will remain alive.
-// Where an instance method is invoked upon a JSValue, and this returns another
-// JSValue, the returned JSValue will originate from the same JSContext as the
-// JSValue on which the method was invoked.
-//
-// For all methods taking arguments of type id, arguments will be converted
-// into a JavaScript value according to the conversion specified below.
-// All JavaScript values are associated with a particular JSVirtualMachine
-// (the associated JSVirtualMachine is available indirectly via the context
-// property). An instance of JSValue may only be passed as an argument to
-// methods on instances of JSValue and JSContext that belong to the same
-// JSVirtualMachine - passing a JSValue to a method on an object originating
-// from a different JSVirtualMachine will result in an Objective-C exception
-// being raised.
-//
-// Conversion between Objective-C and JavaScript types.
-//
-// When converting between JavaScript values and Objective-C objects a copy is
-// performed. Values of types listed below are copied to the corresponding
-// types on conversion in each direction. For NSDictionaries, entries in the
-// dictionary that are keyed by strings are copied onto a JavaScript object.
-// For dictionaries and arrays, conversion is recursive, with the same object
-// conversion being applied to all entries in the collection.
-//
-// Objective-C type | JavaScript type
-// --------------------+---------------------
-// nil | undefined
-// NSNull | null
-// NSString | string
-// NSNumber | number, boolean
-// NSDictionary | Object object
-// NSArray | Array object
-// NSDate | Date object
-// NSBlock * | Function object *
-// id ** | Wrapper object **
-// Class *** | Constructor object ***
-//
-// * Instances of NSBlock with supported arguments types will be presented to
-// JavaScript as a callable Function object. For more information on supported
-// argument types see JSExport.h. If a JavaScript Function originating from an
-// Objective-C block is converted back to an Objective-C object the block will
-// be returned. All other JavaScript functions will be converted in the same
-// manner as a JavaScript object of type Object.
-//
-// ** For Objective-C instances that do not derive from the set of types listed
-// above, a wrapper object to provide a retaining handle to the Objective-C
-// instance from JavaScript. For more information on these wrapper objects, see
-// JSExport.h. When a JavaScript wrapper object is converted back to Objective-C
-// the Objective-C instance being retained by the wrapper is returned.
-//
-// *** For Objective-C Class objects a constructor object containing exported
-// class methods will be returned. See JSExport.h for more information on
-// constructor objects.
</del><ins>+/*!
+@interface
+@discussion A JSValue is a reference to a value within the JavaScript object space of a
+ JSVirtualMachine. All instances of JSValue originate from a JSContext and
+ hold a strong reference to this JSContext. As long as any value associated with
+ a particular JSContext is retained, that JSContext will remain alive.
+ Where an instance method is invoked upon a JSValue, and this returns another
+ JSValue, the returned JSValue will originate from the same JSContext as the
+ JSValue on which the method was invoked.
</ins><span class="cx">
</span><ins>+ All JavaScript values are associated with a particular JSVirtualMachine
+ (the associated JSVirtualMachine is available indirectly via the context
+ property). An instance of JSValue may only be passed as an argument to
+ methods on instances of JSValue and JSContext that belong to the same
+ JSVirtualMachine - passing a JSValue to a method on an object originating
+ from a different JSVirtualMachine will result in an Objective-C exception
+ being raised.
+*/
</ins><span class="cx"> #ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
</span><span class="cx"> NS_CLASS_AVAILABLE(10_9, 7_0)
</span><span class="cx"> #else
</span><span class="lines">@@ -96,162 +57,521 @@
</span><span class="cx"> #endif
</span><span class="cx"> @interface JSValue : NSObject
</span><span class="cx">
</span><del>-// Create a JSValue by converting an Objective-C object.
</del><ins>+/*!
+@property
+@abstract The JSContext that this value originates from.
+*/
+@property(readonly, retain) JSContext *context;
+
+/*!
+@methodgroup Creating JavaScript Values
+*/
+/*!
+@method
+@abstract Create a JSValue by converting an Objective-C object.
+@discussion The resulting JSValue retains the provided Objective-C object.
+@param value The Objective-C object to be converted.
+@result The new JSValue.
+*/
</ins><span class="cx"> + (JSValue *)valueWithObject:(id)value inContext:(JSContext *)context;
</span><del>-// Create a JavaScript value from an Objective-C primitive type.
</del><ins>+
+/*!
+@method
+@abstract Create a JavaScript value from a BOOL primitive.
+@param value
+@param context The JSContext in which the resulting JSValue will be created.
+@result The new JSValue representing the equivalent boolean value.
+*/
</ins><span class="cx"> + (JSValue *)valueWithBool:(BOOL)value inContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a JavaScript value from a double primitive.
+@param value
+@param context The JSContext in which the resulting JSValue will be created.
+@result The new JSValue representing the equivalent boolean value.
+*/
</ins><span class="cx"> + (JSValue *)valueWithDouble:(double)value inContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a JavaScript value from an <code>int32_t</code> primitive.
+@param value
+@param context The JSContext in which the resulting JSValue will be created.
+@result The new JSValue representing the equivalent boolean value.
+*/
</ins><span class="cx"> + (JSValue *)valueWithInt32:(int32_t)value inContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a JavaScript value from a <code>uint32_t</code> primitive.
+@param value
+@param context The JSContext in which the resulting JSValue will be created.
+@result The new JSValue representing the equivalent boolean value.
+*/
</ins><span class="cx"> + (JSValue *)valueWithUInt32:(uint32_t)value inContext:(JSContext *)context;
</span><del>-// Create a JavaScript value in this context.
</del><ins>+
+/*!
+@method
+@abstract Create a new, empty JavaScript object.
+@param context The JSContext in which the resulting object will be created.
+@result The new JavaScript object.
+*/
</ins><span class="cx"> + (JSValue *)valueWithNewObjectInContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a new, empty JavaScript array.
+@param context The JSContext in which the resulting array will be created.
+@result The new JavaScript array.
+*/
</ins><span class="cx"> + (JSValue *)valueWithNewArrayInContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a new JavaScript regular expression object.
+@param pattern The regular expression pattern.
+@param flags The regular expression flags.
+@param context The JSContext in which the resulting regular expression object will be created.
+@result The new JavaScript regular expression object.
+*/
</ins><span class="cx"> + (JSValue *)valueWithNewRegularExpressionFromPattern:(NSString *)pattern flags:(NSString *)flags inContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create a new JavaScript error object.
+@param message The error message.
+@param context The JSContext in which the resulting error object will be created.
+@result The new JavaScript error object.
+*/
</ins><span class="cx"> + (JSValue *)valueWithNewErrorFromMessage:(NSString *)message inContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create the JavaScript value <code>null</code>.
+@param context The JSContext to which the resulting JSValue belongs.
+@result The JSValue representing the JavaScript value <code>null</code>.
+*/
</ins><span class="cx"> + (JSValue *)valueWithNullInContext:(JSContext *)context;
</span><ins>+
+/*!
+@method
+@abstract Create the JavaScript value <code>undefined</code>.
+@param context The JSContext to which the resulting JSValue belongs.
+@result The JSValue representing the JavaScript value <code>undefined</code>.
+*/
</ins><span class="cx"> + (JSValue *)valueWithUndefinedInContext:(JSContext *)context;
</span><span class="cx">
</span><del>-// Convert this value to a corresponding Objective-C object, according to the
-// conversion specified above.
</del><ins>+/*!
+@methodgroup Converting to Objective-C Types
+@discussion When converting between JavaScript values and Objective-C objects a copy is
+ performed. Values of types listed below are copied to the corresponding
+ types on conversion in each direction. For NSDictionaries, entries in the
+ dictionary that are keyed by strings are copied onto a JavaScript object.
+ For dictionaries and arrays, conversion is recursive, with the same object
+ conversion being applied to all entries in the collection.
+
+<pre>
+@textblock
+ Objective-C type | JavaScript type
+ --------------------+---------------------
+ nil | undefined
+ NSNull | null
+ NSString | string
+ NSNumber | number, boolean
+ NSDictionary | Object object
+ NSArray | Array object
+ NSDate | Date object
+ NSBlock (1) | Function object (1)
+ id (2) | Wrapper object (2)
+ Class (3) | Constructor object (3)
+@/textblock
+</pre>
+
+ (1) Instances of NSBlock with supported arguments types will be presented to
+ JavaScript as a callable Function object. For more information on supported
+ argument types see JSExport.h. If a JavaScript Function originating from an
+ Objective-C block is converted back to an Objective-C object the block will
+ be returned. All other JavaScript functions will be converted in the same
+ manner as a JavaScript object of type Object.
+
+ (2) For Objective-C instances that do not derive from the set of types listed
+ above, a wrapper object to provide a retaining handle to the Objective-C
+ instance from JavaScript. For more information on these wrapper objects, see
+ JSExport.h. When a JavaScript wrapper object is converted back to Objective-C
+ the Objective-C instance being retained by the wrapper is returned.
+
+ (3) For Objective-C Class objects a constructor object containing exported
+ class methods will be returned. See JSExport.h for more information on
+ constructor objects.
+
+ For all methods taking arguments of type id, arguments will be converted
+ into a JavaScript value according to the above conversion.
+*/
+/*!
+@method
+@abstract Convert this JSValue to an Objective-C object.
+@discussion The JSValue is converted to an Objective-C object according
+ to the conversion rules specified above.
+@result The Objective-C representation of this JSValue.
+*/
</ins><span class="cx"> - (id)toObject;
</span><del>-// Convert this value to a corresponding Objective-C object, if the result is
-// not of the specified class then nil will be returned.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to an Objective-C object of a specific class.
+@discussion The JSValue is converted to an Objective-C object of the specified Class.
+ If the result is not of the specified Class then <code>nil</code> will be returned.
+@result An Objective-C object of the specified Class or <code>nil</code>.
+*/
</ins><span class="cx"> - (id)toObjectOfClass:(Class)expectedClass;
</span><del>-// The value is copied to a boolean according to the conversion specified by the
-// JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a boolean.
+@discussion The JSValue is converted to a boolean according to the rules specified
+ by the JavaScript language.
+@result The boolean result of the conversion.
+*/
</ins><span class="cx"> - (BOOL)toBool;
</span><del>-// The value is copied to a number according to the conversion specified by the
-// JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a double.
+@discussion The JSValue is converted to a number according to the rules specified
+ by the JavaScript language.
+@result The double result of the conversion.
+*/
</ins><span class="cx"> - (double)toDouble;
</span><del>-// The value is copied to an integer according to the conversion specified by
-// the JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to an <code>int32_t</code>.
+@discussion The JSValue is converted to an integer according to the rules specified
+ by the JavaScript language.
+@result The <code>int32_t</code> result of the conversion.
+*/
</ins><span class="cx"> - (int32_t)toInt32;
</span><del>-// The value is copied to an integer according to the conversion specified by
-// the JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a <code>uint32_t</code>.
+@discussion The JSValue is converted to an integer according to the rules specified
+ by the JavaScript language.
+@result The <code>uint32_t</code> result of the conversion.
+*/
</ins><span class="cx"> - (uint32_t)toUInt32;
</span><del>-// If the value is a boolean, a NSNumber value of @YES or @NO will be returned.
-// For all other types the value will be copied to a number according to the
-// conversion specified by the JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a NSNumber.
+@discussion If the JSValue represents a boolean, a NSNumber value of YES or NO
+ will be returned. For all other types the value will be converted to a number according
+ to the rules specified by the JavaScript language.
+@result The NSNumber result of the conversion.
+*/
</ins><span class="cx"> - (NSNumber *)toNumber;
</span><del>-// The value is copied to a string according to the conversion specified by the
-// JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a NSString.
+@discussion The JSValue is converted to a string according to the rules specified
+ by the JavaScript language.
+@result The NSString containing the result of the conversion.
+*/
</ins><span class="cx"> - (NSString *)toString;
</span><del>-// The value is converted to a number representing a time interval since 1970,
-// and a new NSDate instance is returned.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a NSDate.
+@discussion The value is converted to a number representing a time interval
+ since 1970 which is then used to create a new NSDate instance.
+@result The NSDate created using the converted time interval.
+*/
</ins><span class="cx"> - (NSDate *)toDate;
</span><del>-// If the value is null or undefined then nil is returned.
-// If the value is not an object then a JavaScript TypeError will be thrown.
-// The property "length" is read from the object, converted to an unsigned
-// integer, and an NSArray of this size is allocated. Properties corresponding
-// to indicies within the array bounds will be copied to the array, with
-// Objective-C objects converted to equivalent JSValues as specified.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a NSArray.
+@discussion If the value is <code>null</code> or <code>undefined</code> then <code>nil</code> is returned.
+ If the value is not an object then a JavaScript TypeError will be thrown.
+ The property <code>length</code> is read from the object, converted to an unsigned
+ integer, and an NSArray of this size is allocated. Properties corresponding
+ to indicies within the array bounds will be copied to the array, with
+ JSValues converted to equivalent Objective-C objects as specified.
+@result The NSArray containing the recursively converted contents of the
+ converted JavaScript array.
+*/
</ins><span class="cx"> - (NSArray *)toArray;
</span><del>-// If the value is null or undefined then nil is returned.
-// If the value is not an object then a JavaScript TypeError will be thrown.
-// All enumerable properties of the object are copied to the dictionary, with
-// Objective-C objects converted to equivalent JSValues as specified.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a NSDictionary.
+@discussion If the value is <code>null</code> or <code>undefined</code> then <code>nil</code> is returned.
+ If the value is not an object then a JavaScript TypeError will be thrown.
+ All enumerable properties of the object are copied to the dictionary, with
+ JSValues converted to equivalent Objective-C objects as specified.
+@result The NSDictionary containing the recursively converted contents of
+ the converted JavaScript object.
+*/
</ins><span class="cx"> - (NSDictionary *)toDictionary;
</span><span class="cx">
</span><del>-// Access a property from the value. This method will return the JavaScript value
-// 'undefined' if the property does not exist.
</del><ins>+/*!
+@methodgroup Accessing Properties
+*/
+/*!
+@method
+@abstract Access a property of a JSValue.
+@result The JSValue for the requested property or the JSValue <code>undefined</code>
+ if the property does not exist.
+*/
</ins><span class="cx"> - (JSValue *)valueForProperty:(NSString *)property;
</span><del>-// Set a property on the value.
</del><ins>+
+/*!
+@method
+@abstract Set a property on a JSValue.
+*/
</ins><span class="cx"> - (void)setValue:(id)value forProperty:(NSString *)property;
</span><del>-// Delete a property from the value, returns YES if deletion is successful.
</del><ins>+
+/*!
+@method
+@abstract Delete a property from a JSValue.
+@result YES if deletion is successful, NO otherwise.
+*/
</ins><span class="cx"> - (BOOL)deleteProperty:(NSString *)property;
</span><del>-// Returns YES if property is present on the value.
-// This method has the same function as the JavaScript operator "in".
</del><ins>+
+/*!
+@method
+@abstract Check if a JSValue has a property.
+@discussion This method has the same function as the JavaScript operator <code>in</code>.
+@result Returns YES if property is present on the value.
+*/
</ins><span class="cx"> - (BOOL)hasProperty:(NSString *)property;
</span><del>-// This method may be used to create a data or accessor property on an object;
-// this method operates in accordance with the Object.defineProperty method in
-// the JavaScript language.
</del><ins>+
+/*!
+@method
+@abstract Define properties with custom descriptors on JSValues.
+@discussion This method may be used to create a data or accessor property on an object.
+ This method operates in accordance with the Object.defineProperty method in the
+ JavaScript language.
+*/
</ins><span class="cx"> - (void)defineProperty:(NSString *)property descriptor:(id)descriptor;
</span><span class="cx">
</span><del>-// Access an indexed property from the value. This method will return the
-// JavaScript value 'undefined' if no property exists at that index.
</del><ins>+/*!
+@method
+@abstract Access an indexed (numerical) property on a JSValue.
+@result The JSValue for the property at the specified index.
+ Returns the JavaScript value <code>undefined</code> if no property exists at that index.
+*/
</ins><span class="cx"> - (JSValue *)valueAtIndex:(NSUInteger)index;
</span><del>-// Set an indexed property on the value. For JSValues that are JavaScript arrays,
-// indices greater than UINT_MAX - 1 will not affect the length of the array.
</del><ins>+
+/*!
+@method
+@abstract Set an indexed (numerical) property on a JSValue.
+@discussion For JSValues that are JavaScript arrays, indices greater than
+ UINT_MAX - 1 will not affect the length of the array.
+*/
</ins><span class="cx"> - (void)setValue:(id)value atIndex:(NSUInteger)index;
</span><span class="cx">
</span><del>-// All JavaScript values are precisely one of these types.
</del><ins>+/*!
+@methodgroup Checking JavaScript Types
+*/
+/*!
+@method
+@abstract Check if a JSValue corresponds to the JavaScript value <code>undefined</code>.
+*/
</ins><span class="cx"> - (BOOL)isUndefined;
</span><ins>+
+/*!
+@method
+@abstract Check if a JSValue corresponds to the JavaScript value <code>null</code>.
+*/
</ins><span class="cx"> - (BOOL)isNull;
</span><ins>+
+/*!
+@method
+@abstract Check if a JSValue is a boolean.
+*/
</ins><span class="cx"> - (BOOL)isBoolean;
</span><ins>+
+/*!
+@method
+@abstract Check if a JSValue is a number.
+@discussion In JavaScript, there is no differentiation between types of numbers.
+ Semantically all numbers behave like doubles except in special cases like bit
+ operations.
+*/
</ins><span class="cx"> - (BOOL)isNumber;
</span><ins>+
+/*!
+@method
+@abstract Check if a JSValue is a string.
+*/
</ins><span class="cx"> - (BOOL)isString;
</span><ins>+
+/*!
+@method
+@abstract Check if a JSValue is an object.
+*/
</ins><span class="cx"> - (BOOL)isObject;
</span><span class="cx">
</span><del>-// This method has the same function as the JavaScript operator "===".
</del><ins>+/*!
+@method
+@abstract Compare two JSValues using JavaScript's <code>===</code> operator.
+*/
</ins><span class="cx"> - (BOOL)isEqualToObject:(id)value;
</span><del>-// This method has the same function as the JavaScript operator "==".
</del><ins>+
+/*!
+@method
+@abstract Compare two JSValues using JavaScript's <code>==</code> operator.
+*/
</ins><span class="cx"> - (BOOL)isEqualWithTypeCoercionToObject:(id)value;
</span><del>-// This method has the same function as the JavaScript operator "instanceof".
</del><ins>+
+/*!
+@method
+@abstract Check if a JSValue is an instance of another object.
+@discussion This method has the same function as the JavaScript operator <code>instanceof</code>.
+ If an object other than a JSValue is passed, it will first be converted according to
+ the aforementioned rules.
+*/
</ins><span class="cx"> - (BOOL)isInstanceOf:(id)value;
</span><span class="cx">
</span><del>-// Call this value as a function passing the specified arguments.
</del><ins>+/*!
+@methodgroup Calling Functions and Constructors
+*/
+/*!
+@method
+@abstract Invoke a JSValue as a function.
+@discussion In JavaScript, if a function doesn't explicitly return a value then it
+ implicitly returns the JavaScript value <code>undefined</code>.
+@param arguments The arguments to pass to the function.
+@result The return value of the function call.
+*/
</ins><span class="cx"> - (JSValue *)callWithArguments:(NSArray *)arguments;
</span><del>-// Call this value as a constructor passing the specified arguments.
</del><ins>+
+/*!
+@method
+@abstract Invoke a JSValue as a constructor.
+@discussion This is equivalent to using the <code>new</code> syntax in JavaScript.
+@param arguments The arguments to pass to the constructor.
+@result The return value of the constructor call.
+*/
</ins><span class="cx"> - (JSValue *)constructWithArguments:(NSArray *)arguments;
</span><del>-// Access the property named "method" from this value; call the value resulting
-// from the property access as a function, passing this value as the "this"
-// value, and the specified arguments.
</del><ins>+
+/*!
+@method
+@abstract Invoke a method on a JSValue.
+@discussion Accesses the property named <code>method</code> from this value and
+ calls the resulting value as a function, passing this JSValue as the <code>this</code>
+ value along with the specified arguments.
+@param method The name of the method to be invoked.
+@param arguments The arguments to pass to the method.
+@result The return value of the method call.
+*/
</ins><span class="cx"> - (JSValue *)invokeMethod:(NSString *)method withArguments:(NSArray *)arguments;
</span><span class="cx">
</span><del>-// The JSContext that this value originates from.
-@property(readonly, retain) JSContext *context;
-
</del><span class="cx"> @end
</span><span class="cx">
</span><del>-// Objective-C methods exported to JavaScript may have argument and/or return
-// values of struct types, provided that conversion to and from the struct is
-// supported by JSValue. Support is provided for any types where JSValue
-// contains both a class method "valueWith<Type>:inContext:", and and instance
-// method "to<Type>" - where the string "<Type>" in these selector names match,
-// with the first argument to the former being of the same struct type as the
-// return type of the latter.
-// Support is provided for structs of type CGPoint, NSRange, CGRect and CGSize.
</del><ins>+/*!
+@category
+@discussion Objective-C methods exported to JavaScript may have argument and/or return
+ values of struct types, provided that conversion to and from the struct is
+ supported by JSValue. Support is provided for any types where JSValue
+ contains both a class method <code>valueWith<Type>:inContext:</code>, and and instance
+ method <code>to<Type></code>- where the string <code><Type></code> in these selector names match,
+ with the first argument to the former being of the same struct type as the
+ return type of the latter.
+ Support is provided for structs of type CGPoint, NSRange, CGRect and CGSize.
+*/
</ins><span class="cx"> @interface JSValue(StructSupport)
</span><span class="cx">
</span><del>-// This method returns a newly allocated JavaScript object containing properties
-// named "x" and "y", with values from the CGPoint.
</del><ins>+/*!
+@method
+@abstract Create a JSValue from a CGPoint.
+@result A newly allocated JavaScript object containing properties
+ named <code>x</code> and <code>y</code>, with values from the CGPoint.
+*/
</ins><span class="cx"> + (JSValue *)valueWithPoint:(CGPoint)point inContext:(JSContext *)context;
</span><del>-// This method returns a newly allocated JavaScript object containing properties
-// named "location" and "length", with values from the NSRange.
</del><ins>+
+/*!
+@method
+@abstract Create a JSValue from a NSRange.
+@result A newly allocated JavaScript object containing properties
+ named <code>location</code> and <code>length</code>, with values from the NSRange.
+*/
</ins><span class="cx"> + (JSValue *)valueWithRange:(NSRange)range inContext:(JSContext *)context;
</span><del>-// This method returns a newly allocated JavaScript object containing properties
-// named "x", "y", "width", and "height", with values from the CGRect.
</del><ins>+
+/*!
+@method
+@abstract
+Create a JSValue from a CGRect.
+@result A newly allocated JavaScript object containing properties
+ named <code>x</code>, <code>y</code>, <code>width</code>, and <code>height</code>, with values from the CGRect.
+*/
</ins><span class="cx"> + (JSValue *)valueWithRect:(CGRect)rect inContext:(JSContext *)context;
</span><del>-// This method returns a newly allocated JavaScript object containing properties
-// named "width" and "height", with values from the CGSize.
</del><ins>+
+/*!
+@method
+@abstract Create a JSValue from a CGSize.
+@result A newly allocated JavaScript object containing properties
+ named <code>width</code> and <code>height</code>, with values from the CGSize.
+*/
</ins><span class="cx"> + (JSValue *)valueWithSize:(CGSize)size inContext:(JSContext *)context;
</span><span class="cx">
</span><del>-// Convert a value to type CGPoint by reading properties named "x" and "y" from
-// this value, and converting the results to double.
</del><ins>+/*!
+@method
+@abstract Convert a JSValue to a CGPoint.
+@discussion Reads the properties named <code>x</code> and <code>y</code> from
+ this JSValue, and converts the results to double.
+@result The new CGPoint.
+*/
</ins><span class="cx"> - (CGPoint)toPoint;
</span><del>-// Convert a value to type NSRange by accessing properties named "location" and
-// "length" from this value converting the results to double.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to an NSRange.
+@discussion Reads the properties named <code>location</code> and
+ <code>length</code> from this JSValue and converts the results to double.
+@result The new NSRange.
+*/
</ins><span class="cx"> - (NSRange)toRange;
</span><del>-// Convert a value to type CGRect by reading properties named "x", "y", "width",
-// and "height" from this value, and converting the results to double.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a CGRect.
+@discussion Reads the properties named <code>x</code>, <code>y</code>,
+ <code>width</code>, and <code>height</code> from this JSValue and converts the results to double.
+@result The new CGRect.
+*/
</ins><span class="cx"> - (CGRect)toRect;
</span><del>-// Convert a value to type CGSize by accessing properties named "width" and
-// "height" from this value converting the results to double.
</del><ins>+
+/*!
+@method
+@abstract Convert a JSValue to a CGSize.
+@discussion Reads the properties named <code>width</code> and
+ <code>height</code> from this JSValue and converts the results to double.
+@result The new CGSize.
+*/
</ins><span class="cx"> - (CGSize)toSize;
</span><span class="cx">
</span><span class="cx"> @end
</span><span class="cx">
</span><del>-// Instances of JSValue implement the following methods in order to enable
-// support for subscript access by key and index, for example:
-//
-// JSValue *objectA, *objectB;
-// JSValue *v1 = object[@"X"]; // Get value for property "X" from 'object'.
-// JSValue *v2 = object[42]; // Get value for index 42 from 'object'.
-// object[@"Y"] = v1; // Assign 'v1' to property "Y" of 'object'.
-// object[101] = v2; // Assign 'v2' to index 101 of 'object'.
-//
-// An object key passed as a subscript will be converted to a JavaScript value,
-// and then the value converted to a string used as a property name.
</del><ins>+/*!
+@category
+@discussion Instances of JSValue implement the following methods in order to enable
+ support for subscript access by key and index, for example:
+
+@textblock
+ JSValue *objectA, *objectB;
+ JSValue *v1 = object[@"X"]; // Get value for property "X" from 'object'.
+ JSValue *v2 = object[42]; // Get value for index 42 from 'object'.
+ object[@"Y"] = v1; // Assign 'v1' to property "Y" of 'object'.
+ object[101] = v2; // Assign 'v2' to index 101 of 'object'.
+@/textblock
+
+ An object key passed as a subscript will be converted to a JavaScript value,
+ and then the value converted to a string used as a property name.
+*/
</ins><span class="cx"> @interface JSValue(SubscriptSupport)
</span><span class="cx">
</span><span class="cx"> - (JSValue *)objectForKeyedSubscript:(id)key;
</span><span class="lines">@@ -261,11 +581,26 @@
</span><span class="cx">
</span><span class="cx"> @end
</span><span class="cx">
</span><del>-// These functions are for bridging between the C API and the Objective-C API.
</del><ins>+/*!
+@category
+@discussion These functions are for bridging between the C API and the Objective-C API.
+*/
</ins><span class="cx"> @interface JSValue(JSValueRefSupport)
</span><del>-// Creates a JSValue, wrapping its C API counterpart.
</del><ins>+
+/*!
+@method
+@abstract Creates a JSValue, wrapping its C API counterpart.
+@param value
+@param context
+@result The Objective-C API equivalent of the specified JSValueRef.
+*/
</ins><span class="cx"> + (JSValue *)valueWithJSValueRef:(JSValueRef)value inContext:(JSContext *)context;
</span><del>-// Returns the C API counterpart wrapped by a JSContext.
</del><ins>+
+/*!
+@method
+@abstract Returns the C API counterpart wrapped by a JSContext.
+@result The C API equivalent of this JSValue.
+*/
</ins><span class="cx"> - (JSValueRef)JSValueRef;
</span><span class="cx"> @end
</span><span class="cx">
</span><span class="lines">@@ -273,34 +608,58 @@
</span><span class="cx"> extern "C" {
</span><span class="cx"> #endif
</span><span class="cx">
</span><del>-// These keys may assist in creating a property descriptor for use with the
-// defineProperty method on JSValue.
-// Property descriptors must fit one of three descriptions:
-// Data Descriptor:
-// - A descriptor containing one or both of the keys "value" and "writable",
-// and optionally containing one or both of the keys "enumerable" and
-// "configurable". A data descriptor may not contain either the "get" or
-// "set" key.
-// A data descriptor may be used to create or modify the attributes of a
-// data property on an object (replacing any existing accessor property).
-// Accessor Descriptor:
-// - A descriptor containing one or both of the keys "get" and "set", and
-// optionally containing one or both of the keys "enumerable" and
-// "configurable". An accessor descriptor may not contain either the "value"
-// or "writable" key.
-// An accessor descriptor may be used to create or modify the attributes of
-// an accessor property on an object (replacing any existing data property).
-// Generic Descriptor:
-// - A descriptor containing one or both of the keys "enumerable" and
-// "configurable". A generic descriptor may not contain any of the keys
-// "value", " writable", "get", or "set".
-// A generic descriptor may be used to modify the attributes of an existing
-// data or accessor property, or to create a new data property.
</del><ins>+/*!
+@group Property Descriptor Constants
+@discussion These keys may assist in creating a property descriptor for use with the
+ defineProperty method on JSValue.
+ Property descriptors must fit one of three descriptions:
+
+ Data Descriptor:
+ - A descriptor containing one or both of the keys <code>value</code> and <code>writable</code>,
+ and optionally containing one or both of the keys <code>enumerable</code> and
+ <code>configurable</code>. A data descriptor may not contain either the <code>get</code> or
+ <code>set</code> key.
+ A data descriptor may be used to create or modify the attributes of a
+ data property on an object (replacing any existing accessor property).
+
+ Accessor Descriptor:
+ - A descriptor containing one or both of the keys <code>get</code> and <code>set</code>, and
+ optionally containing one or both of the keys <code>enumerable</code> and
+ <code>configurable</code>. An accessor descriptor may not contain either the <code>value</code>
+ or <code>writable</code> key.
+ An accessor descriptor may be used to create or modify the attributes of
+ an accessor property on an object (replacing any existing data property).
+
+ Generic Descriptor:
+ - A descriptor containing one or both of the keys <code>enumerable</code> and
+ <code>configurable</code>. A generic descriptor may not contain any of the keys
+ <code>value</code>, <code>writable</code>, <code>get</code>, or <code>set</code>.
+ A generic descriptor may be used to modify the attributes of an existing
+ data or accessor property, or to create a new data property.
+*/
+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorWritableKey;
</span><ins>+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorEnumerableKey;
</span><ins>+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorConfigurableKey;
</span><ins>+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorValueKey;
</span><ins>+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorGetKey;
</span><ins>+/*!
+@const
+*/
</ins><span class="cx"> JS_EXPORT extern NSString * const JSPropertyDescriptorSetKey;
</span><span class="cx">
</span><span class="cx"> #ifdef __cplusplus
</span></span></pre></div>
<a id="trunkSourceJavaScriptCoreAPIJSVirtualMachineh"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/API/JSVirtualMachine.h (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/API/JSVirtualMachine.h 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/API/JSVirtualMachine.h 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -27,11 +27,13 @@
</span><span class="cx">
</span><span class="cx"> #if JSC_OBJC_API_ENABLED
</span><span class="cx">
</span><del>-// An instance of JSVirtualMachine represents a single JavaScript "object space"
-// or set of execution resources. Thread safety is supported by locking the
-// virtual machine, with concurrent JavaScript execution supported by allocating
-// separate instances of JSVirtualMachine.
-
</del><ins>+/*!
+@interface
+@discussion An instance of JSVirtualMachine represents a single JavaScript "object space"
+ or set of execution resources. Thread safety is supported by locking the
+ virtual machine, with concurrent JavaScript execution supported by allocating
+ separate instances of JSVirtualMachine.
+*/
</ins><span class="cx"> #ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
</span><span class="cx"> NS_CLASS_AVAILABLE(10_9, 7_0)
</span><span class="cx"> #else
</span><span class="lines">@@ -39,22 +41,44 @@
</span><span class="cx"> #endif
</span><span class="cx"> @interface JSVirtualMachine : NSObject
</span><span class="cx">
</span><del>-// Create a new JSVirtualMachine.
</del><ins>+/*!
+@methodgroup Creating New Virtual Machines
+*/
+/*!
+@method
+@abstract Create a new JSVirtualMachine.
+*/
</ins><span class="cx"> - (id)init;
</span><span class="cx">
</span><del>-// addManagedReference:withOwner and removeManagedReference:withOwner allow
-// clients of JSVirtualMachine to make the JavaScript runtime aware of
-// arbitrary external Objective-C object graphs. The runtime can then use
-// this information to retain any JavaScript values that are referenced
-// from somewhere in said object graph.
-//
-// For correct behavior clients must make their external object graphs
-// reachable from within the JavaScript runtime. If an Objective-C object is
-// reachable from within the JavaScript runtime, all managed references
-// transitively reachable from it as recorded with
-// addManagedReference:withOwner: will be scanned by the garbage collector.
-//
</del><ins>+/*!
+@methodgroup Memory Management
+*/
+/*!
+@method
+@abstract Notify the JSVirtualMachine of an external object relationship.
+@discussion Allows clients of JSVirtualMachine to make the JavaScript runtime aware of
+ arbitrary external Objective-C object graphs. The runtime can then use
+ this information to retain any JavaScript values that are referenced
+ from somewhere in said object graph.
+
+ For correct behavior clients must make their external object graphs
+ reachable from within the JavaScript runtime. If an Objective-C object is
+ reachable from within the JavaScript runtime, all managed references
+ transitively reachable from it as recorded using
+ -addManagedReference:withOwner: will be scanned by the garbage collector.
+@param object The object that the owner points to.
+@param owner The object that owns the pointed to object.
+*/
</ins><span class="cx"> - (void)addManagedReference:(id)object withOwner:(id)owner;
</span><ins>+
+/*!
+@method
+@abstract Notify the JSVirtualMachine that a previous object relationship no longer exists.
+@discussion The JavaScript runtime will continue to scan any references that were
+ reported to it by -addManagedReference:withOwner: until those references are removed.
+@param object The object that was formerly owned.
+@param owner The former owner.
+*/
</ins><span class="cx"> - (void)removeManagedReference:(id)object withOwner:(id)owner;
</span><span class="cx">
</span><span class="cx"> @end
</span></span></pre></div>
<a id="trunkSourceJavaScriptCoreChangeLog"></a>
<div class="modfile"><h4>Modified: trunk/Source/JavaScriptCore/ChangeLog (159722 => 159723)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/Source/JavaScriptCore/ChangeLog 2013-11-23 00:57:51 UTC (rev 159722)
+++ trunk/Source/JavaScriptCore/ChangeLog 2013-11-23 02:54:31 UTC (rev 159723)
</span><span class="lines">@@ -1,3 +1,18 @@
</span><ins>+2013-11-22 Mark Hahnenberg <mhahnenberg@apple.com>
+
+ JSC Obj-C API should have real documentation
+ https://bugs.webkit.org/show_bug.cgi?id=124805
+
+ Reviewed by Geoffrey Garen.
+
+ Massaging the header comments into proper headerdocs.
+
+ * API/JSContext.h:
+ * API/JSExport.h:
+ * API/JSManagedValue.h:
+ * API/JSValue.h:
+ * API/JSVirtualMachine.h:
+
</ins><span class="cx"> 2013-11-22 Filip Pizlo <fpizlo@apple.com>
</span><span class="cx">
</span><span class="cx"> CodeBlock::m_numCalleeRegisters shouldn't also mean frame size, frame size needed for exit, or any other unrelated things
</span></span></pre>
</div>
</div>
</body>
</html>