From 2b68775d33c34a4d88f94db82670e3ae87df0fea Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Wed, 17 Aug 2022 18:30:29 +0100 Subject: [PATCH] Add missing doc comments for more types --- .../JavaScriptEventLoop.swift | 29 +++++++++++++++++++ .../JavaScriptKit/BasicObjects/JSArray.swift | 5 +++- .../JavaScriptKit/BasicObjects/JSDate.swift | 2 +- .../JavaScriptKit/BasicObjects/JSError.swift | 2 +- .../BasicObjects/JSTypedArray.swift | 7 +++-- .../FundamentalObjects/JSBigInt.swift | 3 ++ .../FundamentalObjects/JSClosure.swift | 6 ++-- .../FundamentalObjects/JSSymbol.swift | 3 ++ 8 files changed, 49 insertions(+), 8 deletions(-) diff --git a/Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift b/Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift index c6d10209a..412d321a6 100644 --- a/Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift +++ b/Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift @@ -5,6 +5,35 @@ import _CJavaScriptEventLoop #if compiler(>=5.5) +/** Singleton type responsible for integrating JavaScript event loop as a Swift concurrency executor, conforming to +`SerialExecutor` protocol from the standard library. To utilize it: + +1. Make sure that your target depends on `JavaScriptEventLoop` in your `Packages.swift`: + +```swift +.target( + name: "JavaScriptKitExample", + dependencies: [ + "JavaScriptKit", + .product(name: "JavaScriptEventLoop", package: "JavaScriptKit") + ] +) +``` + +2. Add an explicit import in the code that executes **before* you start using `await` and/or `Task` +APIs (most likely in `main.swift`): + +```swift +import JavaScriptEventLoop +``` + +3. Run this function **before* you start using `await` and/or `Task` APIs (again, most likely in +`main.swift`): + +```swift +JavaScriptEventLoop.installGlobalExecutor() +``` +*/ @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) public final class JavaScriptEventLoop: SerialExecutor, @unchecked Sendable { diff --git a/Sources/JavaScriptKit/BasicObjects/JSArray.swift b/Sources/JavaScriptKit/BasicObjects/JSArray.swift index 2d971daf7..90dba72d8 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSArray.swift @@ -1,4 +1,5 @@ -/// A wrapper around [the JavaScript Array class](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) +/// A wrapper around [the JavaScript `Array` +/// class](https://developer.mozilla.org/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 @@ -35,6 +36,8 @@ extension JSArray: RandomAccessCollection { Iterator(jsObject: jsObject) } + /// Iterator type for `JSArray`, conforming to `IteratorProtocol` from the standard library, which allows + /// easy iteration over elements of `JSArray` instances. public class Iterator: IteratorProtocol { private let jsObject: JSObject private var index = 0 diff --git a/Sources/JavaScriptKit/BasicObjects/JSDate.swift b/Sources/JavaScriptKit/BasicObjects/JSDate.swift index 5a0fd25ee..767374125 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSDate.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSDate.swift @@ -1,4 +1,4 @@ -/** A wrapper around the [JavaScript Date +/** A wrapper around the [JavaScript `Date` class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) that exposes its properties in a type-safe way. This doesn't 100% match the JS API, for example `getMonth`/`setMonth` etc accessor methods are converted to properties, but the rest of it matches diff --git a/Sources/JavaScriptKit/BasicObjects/JSError.swift b/Sources/JavaScriptKit/BasicObjects/JSError.swift index 1d1526a47..e9b006c81 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSError.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSError.swift @@ -1,4 +1,4 @@ -/** A wrapper around [the JavaScript Error +/** A wrapper around [the JavaScript `Error` class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) that exposes its properties in a type-safe way. */ diff --git a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift index a32c22203..ee564ae51 100644 --- a/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift +++ b/Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift @@ -10,8 +10,8 @@ public protocol TypedArrayElement: ConvertibleToJSValue, ConstructibleFromJSValu static var typedArrayClass: JSFunction { get } } -/// A wrapper around all JavaScript [TypedArray](https://developer.mozilla.org/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/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) +/// classes] that exposes their properties in a type-safe way. public class JSTypedArray: JSBridgedClass, ExpressibleByArrayLiteral where Element: TypedArrayElement { public class var constructor: JSFunction? { Element.typedArrayClass } public var jsObject: JSObject @@ -120,6 +120,9 @@ extension UInt8: TypedArrayElement { public static var typedArrayClass = JSObject.global.Uint8Array.function! } +/// A wrapper around [the JavaScript `Uint8ClampedArray` +/// class](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) +/// that exposes its properties in a type-safe and Swifty way. public class JSUInt8ClampedArray: JSTypedArray { override public class var constructor: JSFunction? { JSObject.global.Uint8ClampedArray.function! } } diff --git a/Sources/JavaScriptKit/FundamentalObjects/JSBigInt.swift b/Sources/JavaScriptKit/FundamentalObjects/JSBigInt.swift index 724e969a1..5929f2889 100644 --- a/Sources/JavaScriptKit/FundamentalObjects/JSBigInt.swift +++ b/Sources/JavaScriptKit/FundamentalObjects/JSBigInt.swift @@ -2,6 +2,9 @@ import _CJavaScriptKit private let constructor = JSObject.global.BigInt.function! +/// A wrapper around [the JavaScript `BigInt` +/// class](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) +/// that exposes its properties in a type-safe and Swifty way. public final class JSBigInt: JSObject { @_spi(JSObject_id) override public init(id: JavaScriptObjectRef) { diff --git a/Sources/JavaScriptKit/FundamentalObjects/JSClosure.swift b/Sources/JavaScriptKit/FundamentalObjects/JSClosure.swift index 0bff81403..c19f3ba8b 100644 --- a/Sources/JavaScriptKit/FundamentalObjects/JSClosure.swift +++ b/Sources/JavaScriptKit/FundamentalObjects/JSClosure.swift @@ -1,6 +1,6 @@ import _CJavaScriptKit -/// JSClosureProtocol wraps Swift closure objects for use in JavaScript. Conforming types +/// `JSClosureProtocol` wraps Swift closure objects for use in JavaScript. Conforming types /// are responsible for managing the lifetime of the closure they wrap, but can delegate that /// task to the user by requiring an explicit `release()` call. public protocol JSClosureProtocol: JSValueCompatible { @@ -10,8 +10,8 @@ public protocol JSClosureProtocol: JSValueCompatible { func release() } - -/// `JSOneshotClosure` is a JavaScript function that can be called only once. +/// `JSOneshotClosure` is a JavaScript function that can be called only once. This class can be used +/// for optimized memory management when compared to the common `JSClosure`. public class JSOneshotClosure: JSObject, JSClosureProtocol { private var hostFuncRef: JavaScriptHostFuncRef = 0 diff --git a/Sources/JavaScriptKit/FundamentalObjects/JSSymbol.swift b/Sources/JavaScriptKit/FundamentalObjects/JSSymbol.swift index a0dea3937..f0560ef98 100644 --- a/Sources/JavaScriptKit/FundamentalObjects/JSSymbol.swift +++ b/Sources/JavaScriptKit/FundamentalObjects/JSSymbol.swift @@ -2,6 +2,9 @@ import _CJavaScriptKit private let Symbol = JSObject.global.Symbol.function! +/// A wrapper around [the JavaScript `Symbol` +/// class](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol) +/// that exposes its properties in a type-safe and Swifty way. public class JSSymbol: JSObject { public var name: String? { self["description"].string }