Merge 'wip/next' into dev

Change-Id: Iff9ee5e23bb326c4371ec8ed81d56f2f05d680e9

1 files changed, 37 insertions, 20 deletions

diff --git a/Source/JavaScriptCore/API/JSManagedValue.h b/Source/JavaScriptCore/API/JSManagedValue.h
index 5ff3f83cb..d13733d08 100644
--- a/Source/JavaScriptCore/API/JSManagedValue.h
+++ b/Source/JavaScriptCore/API/JSManagedValue.h
@@ -27,37 +27,54 @@
 #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. 
-NS_CLASS_AVAILABLE(10_9, NA)
+/*!
+@interface
+@discussion JSManagedValue represents a "conditionally retained" JSValue. 
+ "Conditionally retained" means that as long as the JSManagedValue's 
+ JSValue is reachable through the JavaScript object graph,
+ or through the Objective-C object graph reported to the JSVirtualMachine using
+ addManagedReference:withOwner:, the corresponding JSValue will 
+ be retained. However, if neither graph reaches the JSManagedValue, the 
+ corresponding JSValue will be released and set to nil.
+
+The primary use for a JSManagedValue is to store a JSValue in an Objective-C
+or Swift object that is exported to JavaScript. It is incorrect to store a JSValue
+in an object that is exported to JavaScript, since doing so creates a retain cycle.
+*/ 
+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