Add doc comments for public APIs (Part 2) (#57)

* Add doc comments for public APIs (Part 2)

* Update Sources/JavaScriptKit/BasicObjects/JSArray.swift

Co-authored-by: Max Desiatov <[email protected]>

* Update Sources/JavaScriptKit/BasicObjects/JSArray.swift

Co-authored-by: Max Desiatov <[email protected]>

* Update Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift

Co-authored-by: Max Desiatov <[email protected]>

* Update Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift

Co-authored-by: Max Desiatov <[email protected]>

* Update Sources/JavaScriptKit/JSValueConvertible.swift

Co-authored-by: Max Desiatov <[email protected]>

* Update Sources/JavaScriptKit/JSValueDecoder.swift

Co-authored-by: Max Desiatov <[email protected]>

Co-authored-by: Max Desiatov <[email protected]>

Author: kateinoigakukun

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

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<Element>: JSValueConvertible, ExpressibleByArrayLiteral where Element: TypedArrayElement {
     let ref: JSObject
     public func jsValue() -> JSValue {
@@ -29,11 +31,18 @@ public class JSTypedArray<Element>: 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,17 +51,21 @@ public class JSTypedArray<Element>: 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
             _create_typed_array(Element.typedArrayKind, ptr.baseAddress!, Int32(array.count), &resultObj)
         }
         self.init(unsafe: JSObject(id: resultObj))
     }
-
-    public convenience init(_ stride: StrideTo<Element>) where Element: Strideable {
-        self.init(stride.map({ $0 }))
+    
+    /// Convenience initializer for `Sequence`.
+    public convenience init<S: Sequence>(_ sequence: S) {
+        self.init(sequence.map({ $0 }))
     }
 }
 

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

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?
 }
 

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
 }
 

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>(
         _: T.Type = T.self,
         from value: JSValue,