JavaScriptCore-7601.1.46.3.tar.gz

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

diff --git a/API/JSManagedValue.h b/API/JSManagedValue.h
index eb79f747a3a27410c382c1830f9aebe469c75a04..97764eead378365b1019c1e6fd1e0d387cb5f5a2 100644 (file)
--- a/API/JSManagedValue.h
+++ b/API/JSManagedValue.h
@@ -27,37 +27,56 @@
 #define JSManagedValue_h
 
 #import <JavaScriptCore/JSBase.h>
+#import <JavaScriptCore/WebKitAvailability.h>
 
 #if JSC_OBJC_API_ENABLED
 
 @class JSValue;
 @class JSContext;
 
-// 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. 
+/*!
+@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.
+*/ 
 NS_CLASS_AVAILABLE(10_9, 7_0)
 @interface JSManagedValue : NSObject
 
-// Convenience method for creating JSManagedValues from JSValues.
+/*!
+@method
+@abstract Create a JSManagedValue from a JSValue.
+@param value
+@result The new JSManagedValue.
+*/
 + (JSManagedValue *)managedValueWithValue:(JSValue *)value;
++ (JSManagedValue *)managedValueWithValue:(JSValue *)value andOwner:(id)owner NS_AVAILABLE(10_10, 8_0);
 
-// Create a JSManagedValue.
-- (id)initWithValue:(JSValue *)value;
+/*!
+@method
+@abstract Create a JSManagedValue.
+@param value
+@result The new JSManagedValue.
+*/
+- (instancetype)initWithValue:(JSValue *)value;
 
-// Get the JSValue to which this JSManagedValue refers. If the JavaScript value has been collected,
-// this method returns nil.
-- (JSValue *)value;
+/*!
+@property
+@abstract Get the JSValue from the JSManagedValue.
+@result The corresponding JSValue for this JSManagedValue or 
+ nil if the JSValue has been collected.
+*/
+@property (readonly, strong) JSValue *value;
 
 @end