Skip to content

Commit b2148b3

Browse files
author
Mark Hahnenberg
committed
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: Canonical link: https://commits.webkit.org/142974@main git-svn-id: https://svn.webkit.org/repository/webkit/trunk@159723 268f45cc-cd09-0410-ab3c-d52691b4dbfc
1 parent 73fd971 commit b2148b3

6 files changed

Lines changed: 895 additions & 363 deletions

File tree

‎Source/JavaScriptCore/API/JSContext.h‎

Lines changed: 155 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -32,99 +32,194 @@
3232

3333
@class JSVirtualMachine, JSValue;
3434

35-
// An instance of JSContext represents a JavaScript execution environment. All
36-
// JavaScript execution takes place within a context.
37-
// JSContext is also used to manage the life-cycle of objects within the
38-
// JavaScript virtual machine. Every instance of JSValue is associated with a
39-
// JSContext via a strong reference. The JSValue will keep the JSContext it
40-
// references alive so long as the JSValue remains alive. When all of the JSValues
41-
// that reference a particular JSContext have been deallocated the JSContext
42-
// will be deallocated unless it has been previously retained.
43-
35+
/*!
36+
@interface
37+
@discussion An instance of JSContext represents a JavaScript execution environment. All
38+
JavaScript execution takes place within a context.
39+
JSContext is also used to manage the life-cycle of objects within the
40+
JavaScript virtual machine. Every instance of JSValue is associated with a
41+
JSContext via a strong reference. The JSValue will keep the JSContext it
42+
references alive so long as the JSValue remains alive. When all of the JSValues
43+
that reference a particular JSContext have been deallocated the JSContext
44+
will be deallocated unless it has been previously retained.
45+
*/
4446
#ifndef JSC_OBJC_API_AVAILABLE_MAC_OS_X_1080
4547
NS_CLASS_AVAILABLE(10_9, 7_0)
4648
#else
4749
OBJC_VISIBLE
4850
#endif
4951
@interface JSContext : NSObject
5052

51-
// Create a JSContext.
53+
/*!
54+
@methodgroup Creating New JSContexts
55+
*/
56+
/*!
57+
@method
58+
@abstract Create a JSContext.
59+
@result The new context.
60+
*/
5261
- (id)init;
53-
// Create a JSContext in the specified virtual machine.
62+
63+
/*!
64+
@method
65+
@abstract Create a JSContext in the specified virtual machine.
66+
@param virtualMachine The JSVirtualMachine in which the context will be created.
67+
@result The new context.
68+
*/
5469
- (id)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
5570

56-
// Evaluate a string of JavaScript code.
71+
/*!
72+
@methodgroup Evaluating Scripts
73+
*/
74+
/*!
75+
@method
76+
@abstract Evaluate a string of JavaScript code.
77+
@param script A string containing the JavaScript code to evaluate.
78+
@result The last value generated by the script.
79+
*/
5780
- (JSValue *)evaluateScript:(NSString *)script;
5881

59-
// This method retrieves the global object of the JavaScript execution context.
60-
// Instances of JSContext originating from WebKit will return a reference to the
61-
// WindowProxy object.
62-
- (JSValue *)globalObject;
63-
64-
// This method may be called from within an Objective-C block or method invoked
65-
// as a callback from JavaScript to retrieve the callback's context. Outside of
66-
// a callback from JavaScript this method will return nil.
82+
/*!
83+
@methodgroup Callback Accessors
84+
*/
85+
/*!
86+
@method
87+
@abstract Get the JSContext that is currently executing.
88+
@discussion This method may be called from within an Objective-C block or method invoked
89+
as a callback from JavaScript to retrieve the callback's context. Outside of
90+
a callback from JavaScript this method will return nil.
91+
@result The currently executing JSContext or nil if there isn't one.
92+
*/
6793
+ (JSContext *)currentContext;
68-
// This method may be called from within an Objective-C block or method invoked
69-
// as a callback from JavaScript to retrieve the callback's this value. Outside
70-
// of a callback from JavaScript this method will return nil.
94+
95+
/*!
96+
@method
97+
@abstract Get the <code>this</code> value of the currently executing method.
98+
@discussion This method may be called from within an Objective-C block or method invoked
99+
as a callback from JavaScript to retrieve the callback's this value. Outside
100+
of a callback from JavaScript this method will return nil.
101+
@result The current <code>this</code> value or nil if there isn't one.
102+
*/
71103
+ (JSValue *)currentThis;
72-
// This method may be called from within an Objective-C block or method invoked
73-
// as a callback from JavaScript to retrieve the callback's arguments, objects
74-
// in the returned array are instances of JSValue. Outside of a callback from
75-
// JavaScript this method will return nil.
104+
105+
/*!
106+
@method
107+
@abstract Get the arguments to the current callback.
108+
@discussion This method may be called from within an Objective-C block or method invoked
109+
as a callback from JavaScript to retrieve the callback's arguments, objects
110+
in the returned array are instances of JSValue. Outside of a callback from
111+
JavaScript this method will return nil.
112+
@result An NSArray of the arguments nil if there is no current callback.
113+
*/
76114
+ (NSArray *)currentArguments;
77115

78-
// The "exception" property may be used to throw an exception to JavaScript.
79-
// Before a callback is made from JavaScript to an Objective-C block or method,
80-
// the prior value of the exception property will be preserved and the property
81-
// will be set to nil. After the callback has completed the new value of the
82-
// exception property will be read, and prior value restored. If the new value
83-
// of exception is not nil, the callback will result in that value being thrown.
84-
// This property may also be used to check for uncaught exceptions arising from
85-
// API function calls (since the default behaviour of "exceptionHandler" is to
86-
// assign an uncaught exception to this property).
87-
// If a JSValue originating from a different JSVirtualMachine than this context
88-
// is assigned to this property, an Objective-C exception will be raised.
116+
/*!
117+
@methodgroup Global Properties
118+
*/
119+
/*!
120+
@method
121+
@abstract Get the global object of the context.
122+
@discussion This method retrieves the global object of the JavaScript execution context.
123+
Instances of JSContext originating from WebKit will return a reference to the
124+
WindowProxy object.
125+
@result The global object.
126+
*/
127+
- (JSValue *)globalObject;
128+
129+
/*!
130+
@property
131+
@discussion The <code>exception</code> property may be used to throw an exception to JavaScript.
132+
133+
Before a callback is made from JavaScript to an Objective-C block or method,
134+
the prior value of the exception property will be preserved and the property
135+
will be set to nil. After the callback has completed the new value of the
136+
exception property will be read, and prior value restored. If the new value
137+
of exception is not nil, the callback will result in that value being thrown.
138+
139+
This property may also be used to check for uncaught exceptions arising from
140+
API function calls (since the default behaviour of <code>exceptionHandler</code> is to
141+
assign an uncaught exception to this property).
142+
143+
If a JSValue originating from a different JSVirtualMachine than this context
144+
is assigned to this property, an Objective-C exception will be raised.
145+
*/
89146
@property(retain) JSValue *exception;
90147

91-
// If a call to an API function results in an uncaught JavaScript exception, the
92-
// "exceptionHandler" block will be invoked. The default implementation for the
93-
// exception handler will store the exception to the exception property on
94-
// context. As a consequence the default behaviour is for unhandled exceptions
95-
// occurring within a callback from JavaScript to be rethrown upon return.
96-
// Setting this value to nil will result in all uncaught exceptions thrown from
97-
// the API being silently consumed.
148+
/*!
149+
@property
150+
@discussion If a call to an API function results in an uncaught JavaScript exception, the
151+
<code>exceptionHandler</code> block will be invoked. The default implementation for the
152+
exception handler will store the exception to the exception property on
153+
context. As a consequence the default behaviour is for unhandled exceptions
154+
occurring within a callback from JavaScript to be rethrown upon return.
155+
Setting this value to nil will result in all uncaught exceptions thrown from
156+
the API being silently consumed.
157+
*/
98158
@property(copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
99159

100-
// All instances of JSContext are associated with a single JSVirtualMachine. The
101-
// virtual machine provides an "object space" or set of execution resources.
160+
/*!
161+
@property
162+
@discussion All instances of JSContext are associated with a single JSVirtualMachine. The
163+
virtual machine provides an "object space" or set of execution resources.
164+
*/
102165
@property(readonly, retain) JSVirtualMachine *virtualMachine;
103166

104167
@end
105168

106-
// Instances of JSContext implement the following methods in order to enable
107-
// support for subscript access by key and index, for example:
108-
//
109-
// JSContext *context;
110-
// JSValue *v = context[@"X"]; // Get value for "X" from the global object.
111-
// context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
112-
//
113-
// An object key passed as a subscript will be converted to a JavaScript value,
114-
// and then the value converted to a string used to resolve a property of the
115-
// global object.
169+
/*!
170+
@category
171+
@discussion Instances of JSContext implement the following methods in order to enable
172+
support for subscript access by key and index, for example:
173+
174+
@textblock
175+
JSContext *context;
176+
JSValue *v = context[@"X"]; // Get value for "X" from the global object.
177+
context[@"Y"] = v; // Assign 'v' to "Y" on the global object.
178+
@/textblock
179+
180+
An object key passed as a subscript will be converted to a JavaScript value,
181+
and then the value converted to a string used to resolve a property of the
182+
global object.
183+
*/
116184
@interface JSContext(SubscriptSupport)
117185

186+
/*!
187+
method
188+
@abstract Get a particular property on the global object.
189+
@param key
190+
@result The JSValue for the global object's property.
191+
*/
118192
- (JSValue *)objectForKeyedSubscript:(id)key;
193+
194+
/*!
195+
method
196+
@abstract Set a particular property on the global object.
197+
@param object
198+
@param key
199+
*/
119200
- (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
120201

121202
@end
122203

123-
// These functions are for bridging between the C API and the Objective-C API.
204+
/*!
205+
@category
206+
@discussion These functions are for bridging between the C API and the Objective-C API.
207+
*/
124208
@interface JSContext(JSContextRefSupport)
125-
// Creates a JSContext, wrapping its C API counterpart.
209+
210+
/*!
211+
@method
212+
@abstract Create a JSContext, wrapping its C API counterpart.
213+
@param jsGlobalContextRef
214+
@result The JSContext equivalent of the provided JSGlobalContextRef.
215+
*/
126216
+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
127-
// Returns the C API counterpart wrapped by a JSContext.
217+
218+
/*!
219+
@method
220+
@abstract Get the C API counterpart wrapped by a JSContext.
221+
@result The C API equivalent of this JSContext.
222+
*/
128223
- (JSGlobalContextRef)JSGlobalContextRef;
129224
@end
130225

0 commit comments

Comments
 (0)