Merge branch 'master' into webidl

Sources/JavaScriptKit/BasicObjects/JSArray.swift

@@ -1,3 +1,5 @@
+/// A wrapper around [the JavaScript Array class](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array)
+/// that exposes its properties in a type-safe and Swifty way.
 public class JSArray: JSBridgedClass {
     public static let constructor = JSObject.global.Array.function!
 
@@ -12,10 +14,15 @@ public class JSArray: JSBridgedClass {
         self.init(object)
     }
 
+    /// Construct a `JSArray` from Array `JSObject`.
+    /// Return `nil` if the object is not an Array.
+    ///
+    /// - Parameter object: A `JSObject` expected to be a JavaScript Array
     public convenience init?(_ jsObject: JSObject) {
         guard Self.isArray(jsObject) else { return nil }
         self.init(withCompatibleObject: jsObject)
     }
+
     public required init(withCompatibleObject jsObject: JSObject) {
         self.jsObject = jsObject
     }

Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift

@@ -6,13 +6,12 @@ import _CJavaScriptKit
 
 /// A protocol that allows a Swift numeric type to be mapped to the JavaScript TypedArray that holds integers of its type
 public protocol TypedArrayElement: JSValueConvertible, JSValueConstructible {
-    /// The kind of typed array that should be created on the JS side
-    static var typedArrayKind: JavaScriptTypedArrayKind { get }
     /// The constructor function for the TypedArray class for this particular kind of number
     static var typedArrayClass: JSFunction { get }
 }
 
-/// A wrapper around all JavaScript [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) classes that exposes their properties in a type-safe way.
+/// A wrapper around all JavaScript [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) classes that exposes their properties in a type-safe way.
+/// FIXME: the BigInt-based TypedArrays are not supported (https://github.com/swiftwasm/JavaScriptKit/issues/56)
 public class JSTypedArray<Element>: JSBridgedClass, ExpressibleByArrayLiteral where Element: TypedArrayElement {
     public static var constructor: JSFunction { Element.typedArrayClass }
     public var jsObject: JSObject
@@ -26,7 +25,10 @@ public class JSTypedArray<Element>: JSBridgedClass, ExpressibleByArrayLiteral wh
         }
     }
 
-    /// Create a TypedArray with the provided number of elements allocated. All the elements will be initialized to zero.
+    /// Initialize a new instance of TypedArray in JavaScript environment with given length.
+    ///  All the elements will be initialized to zero.
+    ///
+    /// - Parameter length: The number of elements that will be allocated.
     public init(length: Int) {
         jsObject = Element.typedArrayClass.new(length)
     }
@@ -38,8 +40,9 @@ public class JSTypedArray<Element>: JSBridgedClass, ExpressibleByArrayLiteral wh
     required public convenience init(arrayLiteral elements: Element...) {
         self.init(elements)
     }
-
-    /// Convert an array of numbers into a JavaScript TypedArray
+    /// Initialize a new instance of TypedArray in JavaScript environment with given elements.
+    ///
+    /// - Parameter array: The array that will be copied to create a new instance of TypedArray
     public convenience init(_ array: [Element]) {
         var resultObj = JavaScriptObjectRef()
         array.withUnsafeBufferPointer { ptr in
@@ -76,8 +79,6 @@ extension UInt: TypedArrayElement {
         valueForBitWidth(typeName: "UInt", bitWidth: Int.bitWidth, when32: JSObject.global.Uint32Array).function!
 }
 
-// MARK: - Concrete TypedArray classes
-
 extension Int8: TypedArrayElement {
     public static var typedArrayClass = JSObject.global.Int8Array.function!
 }

Sources/JavaScriptKit/FundamentalObjects/JSObject.swift

@@ -39,11 +39,15 @@ public class JSObject: Equatable {
         }
     }
 
+    /// A convenience method of `subscript(_ name: String) -> ((JSValueConvertible...) -> JSValue)?`
+    /// to access the member through Dynamic Member Lookup.
     @_disfavoredOverload
     public subscript(dynamicMember name: String) -> ((JSValueConvertible...) -> JSValue)? {
         self[name]
     }
 
+    /// A convenience method of `subscript(_ name: String) -> JSValue`
+    /// to access the member through Dynamic Member Lookup.
     public subscript(dynamicMember name: String) -> JSValue {
         get { self[name] }
         set { self[name] = newValue }

Sources/JavaScriptKit/JSValue.swift

@@ -46,6 +46,8 @@ public enum JSValue: Equatable {
         }
     }
 
+    /// Returns the `JSFunction` of this JS value if its type is function.
+    /// If not, returns `nil`.
     public var function: JSFunction? {
         switch self {
         case let .function(function): return function
@@ -73,18 +75,22 @@ public enum JSValue: Equatable {
         return true
     }
 
+    public var isFunction: Bool {
+        guard case .function = self else { return false }
+        return true
+    }
+
+    /// Returns the `true` if this JS value is null.
+    /// If not, returns `false`.
     public var isNull: Bool {
         return self == .null
     }
 
+    /// Returns the `true` if this JS value is undefined.
+    /// If not, returns `false`.
     public var isUndefined: Bool {
         return self == .undefined
     }
-
-    public var isFunction: Bool {
-        guard case .function = self else { return false }
-        return true
-    }
 }
 
 extension JSValue {

Sources/JavaScriptKit/JSValueConstructible.swift

@@ -1,6 +1,10 @@
-/// Objects that can be constructed from a JavaScript value
+/// Types conforming to this protocol can be constructed from `JSValue`.
 public protocol JSValueConstructible {
+    /// Construct an instance of `Self`, if possible, from the given `JSValue`.
     /// Return `nil` if the value is not compatible with the conforming Swift type.
+    ///
+    /// - Parameter value: The `JSValue` to decode
+    /// - Returns: An instance of `Self`, if one was successfully constructed from the value.
     static func construct(from value: JSValue) -> Self?
 }