Skip to content

Add missing doc comments for more types #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 17, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down
5 changes: 4 additions & 1 deletion Sources/JavaScriptKit/BasicObjects/JSArray.swift
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Sources/JavaScriptKit/BasicObjects/JSDate.swift
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion Sources/JavaScriptKit/BasicObjects/JSError.swift
Original file line number Diff line number Diff line change
@@ -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.
*/
Expand Down
7 changes: 5 additions & 2 deletions Sources/JavaScriptKit/BasicObjects/JSTypedArray.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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<Element>: JSBridgedClass, ExpressibleByArrayLiteral where Element: TypedArrayElement {
public class var constructor: JSFunction? { Element.typedArrayClass }
public var jsObject: JSObject
Expand Down Expand Up @@ -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<UInt8> {
override public class var constructor: JSFunction? { JSObject.global.Uint8ClampedArray.function! }
}
Expand Down
3 changes: 3 additions & 0 deletions Sources/JavaScriptKit/FundamentalObjects/JSBigInt.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
6 changes: 3 additions & 3 deletions Sources/JavaScriptKit/FundamentalObjects/JSClosure.swift
Original file line number Diff line number Diff line change
@@ -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 {
Expand All @@ -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

Expand Down
3 changes: 3 additions & 0 deletions Sources/JavaScriptKit/FundamentalObjects/JSSymbol.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 }

Expand Down