From 2f818cb9e596abeec7335d98a18de25227669784 Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:02:06 +0900 Subject: [PATCH 1/7] Add doc comments for public APIs (Part 2) --- .../JavaScriptKit/BasicObjects/JSArray.swift | 8 ++++++- .../BasicObjects/JSTypedArray.swift | 21 +++++++++++++++---- Sources/JavaScriptKit/Compatibility.swift | 3 +++ .../JavaScriptKit/JSValueConstructible.swift | 6 ++++++ .../JavaScriptKit/JSValueConvertible.swift | 2 ++ Sources/JavaScriptKit/JSValueDecoder.swift | 7 +++++++ 6 files changed, 42 insertions(+), 5 deletions(-) diff --git a/Sources/JavaScriptKit/BasicObjects/JSArray.swift b/Sources/JavaScriptKit/BasicObjects/JSArray.swift index 4a8a6aecc..ac95cbc31 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 Array. + /// + /// - Parameter object: A `JSObject` expected to be Array of JavaScript 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..ccfa10f83 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..ae1a9d136 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 `JSValue` func jsValue() -> JSValue } diff --git a/Sources/JavaScriptKit/JSValueDecoder.swift b/Sources/JavaScriptKit/JSValueDecoder.swift index e5c2d5bbd..5006f1792 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, From d0160d449d53f38b0ca95b6f54fb6f189de6c630 Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:08:36 +0900 Subject: [PATCH 2/7] Update Sources/JavaScriptKit/BasicObjects/JSArray.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/BasicObjects/JSArray.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/BasicObjects/JSArray.swift b/Sources/JavaScriptKit/BasicObjects/JSArray.swift index ac95cbc31..d62a6bc6c 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSArray.swift @@ -10,7 +10,7 @@ public class JSArray { let ref: JSObject /// Construct a `JSArray` from Array `JSObject`. - /// Return `nil` if the object is not Array. + /// Return `nil` if the object is not an Array. /// /// - Parameter object: A `JSObject` expected to be Array of JavaScript public init?(_ ref: JSObject) { From d2a13fb36892848affb9e3cbec0d7fc387c61e9a Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:08:44 +0900 Subject: [PATCH 3/7] Update Sources/JavaScriptKit/BasicObjects/JSArray.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/BasicObjects/JSArray.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/BasicObjects/JSArray.swift b/Sources/JavaScriptKit/BasicObjects/JSArray.swift index d62a6bc6c..4d5bf231f 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSArray.swift @@ -12,7 +12,7 @@ public class JSArray { /// Construct a `JSArray` from Array `JSObject`. /// Return `nil` if the object is not an Array. /// - /// - Parameter object: A `JSObject` expected to be Array of JavaScript + /// - Parameter object: A `JSObject` expected to be a JavaScript Array public init?(_ ref: JSObject) { guard Self.isArray(ref) else { return nil } self.ref = ref From ab0d6a8cc9bb318f735de6fa93c9a3be7b9c0d72 Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:08:52 +0900 Subject: [PATCH 4/7] Update Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift index ccfa10f83..6bc4359be 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift @@ -40,7 +40,7 @@ public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLitera self.ref = object } - /// Initialize a new instance of TypedArray in JavaScript environment with given length zero value + /// 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) { From a3c865259cb2ca8f06d416219b657cc7b25d3b1e Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:08:59 +0900 Subject: [PATCH 5/7] Update Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift index 6bc4359be..5f4830eab 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift @@ -52,7 +52,7 @@ public class JSTypedArray: JSValueConvertible, ExpressibleByArrayLitera self.init(elements) } - /// Initialize a new instance of TypedArray in JavaScript environment with given 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]) { From 0f4f2e23b0071126ad9226c3b7c92c828e130229 Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:09:06 +0900 Subject: [PATCH 6/7] Update Sources/JavaScriptKit/JSValueConvertible.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/JSValueConvertible.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/JSValueConvertible.swift b/Sources/JavaScriptKit/JSValueConvertible.swift index ae1a9d136..4b4c7e641 100644 --- a/Sources/JavaScriptKit/JSValueConvertible.swift +++ b/Sources/JavaScriptKit/JSValueConvertible.swift @@ -2,7 +2,7 @@ import _CJavaScriptKit /// Confirming types are convertible to `JSValue`. public protocol JSValueConvertible { - /// Convert this object into `JSValue` + /// Convert this object into a `JSValue`. func jsValue() -> JSValue } From 2c9299d0bf56a5e6d70204d088ba2b9edb4e52c7 Mon Sep 17 00:00:00 2001 From: Yuta Saito Date: Wed, 16 Sep 2020 23:09:12 +0900 Subject: [PATCH 7/7] Update Sources/JavaScriptKit/JSValueDecoder.swift Co-authored-by: Max Desiatov --- Sources/JavaScriptKit/JSValueDecoder.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JavaScriptKit/JSValueDecoder.swift b/Sources/JavaScriptKit/JSValueDecoder.swift index 5006f1792..0c6daf824 100644 --- a/Sources/JavaScriptKit/JSValueDecoder.swift +++ b/Sources/JavaScriptKit/JSValueDecoder.swift @@ -232,7 +232,7 @@ extension _Decoder: SingleValueDecodingContainer { /// `JSValueDecoder` facilitates the decoding of JavaScript value into semantic `Decodable` types. public class JSValueDecoder { - /// Initializes a new `JSValueDecoder` + /// Initializes a new `JSValueDecoder`. public init() {} /// Decodes a top-level value of the given type from the given JavaScript value representation.