diff --git a/Sources/JavaScriptKit/BasicObjects/JSArray.swift b/Sources/JavaScriptKit/BasicObjects/JSArray.swift index 4a8a6aecc..4d5bf231f 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSArray.swift +++ b/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 { static let classObject = JSObject.global.Array.function! @@ -6,7 +8,11 @@ public class JSArray { } let ref: JSObject - + + /// 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 init?(_ ref: JSObject) { guard Self.isArray(ref) else { return nil } self.ref = ref diff --git a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift index 0994708ce..5f4830eab 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift @@ -9,6 +9,8 @@ public protocol TypedArrayElement: JSValueConvertible, JSValueConstructible { static var typedArrayClass: JSFunction { get } } +/// A wrapper around [the JavaScript TypedArray class](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +/// that exposes its properties in a type-safe and Swifty way. public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLiteral where Element: TypedArrayElement { let ref: JSObject public func jsValue() -> JSValue { @@ -29,11 +31,18 @@ public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLitera self.ref = object } + /// Construct a `JSTypedArray` from TypedArray `JSObject`. + /// Return `nil` if the object is not TypedArray. + /// + /// - Parameter object: A `JSObject` expected to be TypedArray public init?(_ object: JSObject) { guard object.isInstanceOf(Element.typedArrayClass) else { return nil } self.ref = object } + /// Initialize a new instance of TypedArray in JavaScript environment with given length zero value. + /// + /// - Parameter length: The length of elements that will be allocated. public convenience init(length: Int) { let jsObject = Element.typedArrayClass.new(length) self.init(unsafe: jsObject) @@ -42,7 +51,10 @@ public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLitera required public convenience init(arrayLiteral elements: Element...) { self.init(elements) } - + + /// 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 @@ -50,9 +62,10 @@ public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLitera } self.init(unsafe: JSObject(id: resultObj)) } - - public convenience init(_ stride: StrideTo) where Element: Strideable { - self.init(stride.map({ $0 })) + + /// Convenience initializer for `Sequence`. + public convenience init(_ sequence: S) { + self.init(sequence.map({ $0 })) } } diff --git a/Sources/JavaScriptKit/Compatibility.swift b/Sources/JavaScriptKit/Compatibility.swift index 24952a61f..319068cfd 100644 --- a/Sources/JavaScriptKit/Compatibility.swift +++ b/Sources/JavaScriptKit/Compatibility.swift @@ -1,3 +1,6 @@ +/// The compatibility runtime library version. +/// Notes: If you change any interface of runtime library, please increment +/// this and `SwiftRuntime.version` in `./Runtime/src/index.ts`. @_cdecl("swjs_library_version") func _library_version() -> Double { return 600 diff --git a/Sources/JavaScriptKit/JSValueConstructible.swift b/Sources/JavaScriptKit/JSValueConstructible.swift index 2a312bf65..59a8c63d2 100644 --- a/Sources/JavaScriptKit/JSValueConstructible.swift +++ b/Sources/JavaScriptKit/JSValueConstructible.swift @@ -1,4 +1,10 @@ +/// 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 fail to construct. + /// + /// - 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? } diff --git a/Sources/JavaScriptKit/JSValueConvertible.swift b/Sources/JavaScriptKit/JSValueConvertible.swift index bc3b3491e..4b4c7e641 100644 --- a/Sources/JavaScriptKit/JSValueConvertible.swift +++ b/Sources/JavaScriptKit/JSValueConvertible.swift @@ -1,6 +1,8 @@ import _CJavaScriptKit +/// Confirming types are convertible to `JSValue`. public protocol JSValueConvertible { + /// Convert this object into a `JSValue`. func jsValue() -> JSValue } diff --git a/Sources/JavaScriptKit/JSValueDecoder.swift b/Sources/JavaScriptKit/JSValueDecoder.swift index e5c2d5bbd..0c6daf824 100644 --- a/Sources/JavaScriptKit/JSValueDecoder.swift +++ b/Sources/JavaScriptKit/JSValueDecoder.swift @@ -229,9 +229,16 @@ extension _Decoder: SingleValueDecodingContainer { } } +/// `JSValueDecoder` facilitates the decoding of JavaScript value into semantic `Decodable` types. public class JSValueDecoder { + + /// Initializes a new `JSValueDecoder`. public init() {} + /// Decodes a top-level value of the given type from the given JavaScript value representation. + /// + /// - Parameter T: The type of the value to decode. + /// - Parameter value: The `JSValue` to decode from. public func decode( _: T.Type = T.self, from value: JSValue,