#if JSC_OBJC_API_ENABLED
-// 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.
+/*!
+@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.
+*/
@protocol JSExport
@end
-// 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.
+/*!
+@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.
+*/
#define JSExportAs(PropertyName, Selector) \
@optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector
projects / apple / javascriptcore.git / blobdiff