JavaScriptCore-7600.1.4.11.8.tar.gz

[apple/javascriptcore.git] / API / JSContext.h

diff --git a/API/JSContext.h b/API/JSContext.h
index bffecc0940eb08420d01f1dcb7c59119962d6de4..d9dcc21e84c37ae7d9ed61c4bc663f6613f94e4c 100644 (file)
--- a/API/JSContext.h
+++ b/API/JSContext.h
@@ -20,108 +20,233 @@
  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  */
 
 #ifndef JSContext_h
 #define JSContext_h
 
 #include <JavaScriptCore/JavaScript.h>
  */
 
 #ifndef JSContext_h
 #define JSContext_h
 
 #include <JavaScriptCore/JavaScript.h>

+#include <JavaScriptCore/WebKitAvailability.h>

 
 #if JSC_OBJC_API_ENABLED
 
 @class JSVirtualMachine, JSValue;
 
 
 #if JSC_OBJC_API_ENABLED
 
 @class JSVirtualMachine, JSValue;
 

-// 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.
-
+/*!
+@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.
+*/
+#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080

 NS_CLASS_AVAILABLE(10_9, 7_0)
 NS_CLASS_AVAILABLE(10_9, 7_0)

+#else
+OBJC_VISIBLE
+#endif

 @interface JSContext : NSObject
 
 @interface JSContext : NSObject
 

-// Create a JSContext.
-- (id)init;
-// Create a JSContext in the specified virtual machine.
-- (id)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
-
-// Evaluate a string of JavaScript code.
+/*!
+@methodgroup Creating New JSContexts
+*/
+/*!
+@method
+@abstract Create a JSContext.
+@result The new context.
+*/
+- (instancetype)init;
+
+/*!
+@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.
+*/
+- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
+
+/*!
+@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.
+*/

 - (JSValue *)evaluateScript:(NSString *)script;
 
 - (JSValue *)evaluateScript:(NSString *)script;
 

-// 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;
-
-// 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.
+/*!
+@method
+@abstract Evaluate a string of JavaScript code, with a URL for the script's source file.
+@param script A string containing the JavaScript code to evaluate.
+@param sourceURL A URL for the script's source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script.
+@result The last value generated by the script.
+*/
+- (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL NS_AVAILABLE(10_10, 8_0);
+
+/*!
+@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;
 + (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.
+
+/*!
+@method
+@abstract Get the JavaScript function 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 JavaScript function or nil if there isn't one.
+*/
++ (JSValue *)currentCallee NS_AVAILABLE(10_10, 8_0);
+
+/*!
+@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.
+*/

 + (JSValue *)currentThis;
 + (JSValue *)currentThis;

-// 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.
+
+/*!
+@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.
+*/

 + (NSArray *)currentArguments;
 
 + (NSArray *)currentArguments;
 

-// 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.
-@property(retain) JSValue *exception;
-
-// 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.
-@property(copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
-
-// All instances of JSContext are associated with a single JSVirtualMachine. The
-// virtual machine provides an "object space" or set of execution resources.
-@property(readonly, retain) JSVirtualMachine *virtualMachine;
+/*!
+@methodgroup Global Properties
+*/
+/*!
+@property
+@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.
+*/
+@property (readonly, strong) 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.
+*/
+@property (strong) JSValue *exception;
+
+/*!
+@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.
+*/
+@property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
+
+/*!
+@property
+@discussion All instances of JSContext are associated with a single JSVirtualMachine. The
+ virtual machine provides an "object space" or set of execution resources.
+*/
+@property (readonly, strong) JSVirtualMachine *virtualMachine;
+
+/*!
+@property
+@discussion Name of the JSContext. Exposed when remote debugging the context.
+*/
+@property (copy) NSString *name NS_AVAILABLE(10_10, 8_0);

 
 @end
 
 
 @end
 

-// 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.
-@interface JSContext(SubscriptSupport)
-
+/*!
+@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.
+*/
+@interface JSContext (SubscriptSupport)
+
+/*!
+method
+@abstract Get a particular property on the global object.
+@param key
+@result The JSValue for the global object's property.
+*/

 - (JSValue *)objectForKeyedSubscript:(id)key;
 - (JSValue *)objectForKeyedSubscript:(id)key;

+
+/*!
+method
+@abstract Set a particular property on the global object.
+@param object
+@param key
+*/

 - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
 
 @end
 
 - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
 
 @end
 

-// These functions are for bridging between the C API and the Objective-C API.
-@interface JSContext(JSContextRefSupport)
-// Creates a JSContext, wrapping its C API counterpart.
+/*!
+@category
+@discussion These functions are for bridging between the C API and the Objective-C API.
+*/
+@interface JSContext (JSContextRefSupport)
+
+/*!
+@method
+@abstract Create a JSContext, wrapping its C API counterpart.
+@param jsGlobalContextRef
+@result The JSContext equivalent of the provided JSGlobalContextRef.
+*/

 + (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
 + (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;

-// Returns the C API counterpart wrapped by a JSContext.
-- (JSGlobalContextRef)JSGlobalContextRef;
+
+/*!
+@property
+@abstract Get the C API counterpart wrapped by a JSContext.
+@result The C API equivalent of this JSContext.
+*/
+@property (readonly) JSGlobalContextRef JSGlobalContextRef;

 @end
 
 #endif
 @end
 
 #endif