Skip to content

Add documentation comments for AsyncButton #3

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.

Sign up for GitHub

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
Nov 3, 2023
Merged

Add documentation comments for AsyncButton #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,3 +66,7 @@ Finally, add `import AsyncSwiftUI` to your source code (or replace the existing
| SwiftUI | AsyncSwiftUI |
|:---------------------------------------------------------------------|:--------------|
| [`Button`](https://developer.apple.com/documentation/swiftui/button) | `AsyncButton` |

## Note

The documentation comments included in this library, with some exceptions, are from [the SwiftUI entry in the Apple Developer Documentation](https://developer.apple.com/documentation/swiftui).
88 changes: 88 additions & 0 deletions Sources/Control/AsyncButton.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
import Core
import SwiftUI

/// A control that initiates an action.
/// - SeeAlso: [`SwiftUI.Button`](https://developer.apple.com/documentation/swiftui/button)
@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
public struct AsyncButton<Label: View>: AsyncControl {
public typealias Base = Button<Label>
Expand Down Expand Up @@ -42,6 +44,12 @@ public struct AsyncButton<Label: View>: AsyncControl {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton {
/// Creates a button that displays a custom label.
///
/// - Parameters:
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
/// - label: A view that describes the purpose of the button's `action`.
public init(
priority: TaskPriority = .userInitiated,
@_inheritActorContext action: @escaping @Sendable () async -> Void,
Expand All @@ -59,6 +67,11 @@ extension AsyncButton {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton where Label == Text {
/// Creates a button that generates its label from a localized string key.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
priority: TaskPriority = .userInitiated,
Expand All @@ -73,6 +86,11 @@ extension AsyncButton where Label == Text {
)
}

/// Creates a button that generates its label from a string.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand All @@ -91,6 +109,12 @@ extension AsyncButton where Label == Text {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
/// Creates a button that generates its label from a localized string key and system image name.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - systemImage: The name of the image resource to lookup.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
systemImage: String,
Expand All @@ -106,6 +130,12 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
)
}

/// Creates a button that generates its label from a string and system image name.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - systemImage: The name of the image resource to lookup.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand All @@ -125,6 +155,12 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {

@available(iOS 17.0, macOS 14.0, macCatalyst 17.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
/// Creates a button that generates its label from a localized string key and image resource.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - image: The image resource to lookup.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
image: ImageResource,
Expand All @@ -140,6 +176,12 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
)
}

/// Creates a button that generates its label from a string and image resource.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - image: The image resource to lookup.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand All @@ -159,6 +201,12 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton {
/// Creates a button with a specified role that displays a custom label.
/// - Parameters:
/// - role: An optional semantic role that describes the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user interacts with the button.
/// - label: A view that describes the purpose of the button's `action`.
public init(
role: ButtonRole?,
priority: TaskPriority = .userInitiated,
Expand All @@ -177,6 +225,12 @@ extension AsyncButton {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton where Label == Text {
/// Creates a button with a specified role that generates its label from a localized string key.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
role: ButtonRole?,
Expand All @@ -192,6 +246,12 @@ extension AsyncButton where Label == Text {
)
}

/// Creates a button with a specified role that generates its label from a string.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user interacts with the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand All @@ -211,6 +271,13 @@ extension AsyncButton where Label == Text {

@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, visionOS 1.0, *)
extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
/// Creates a button with a specified role that generates its label from a localized string key and a system image.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - systemImage: The name of the image resource to lookup.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
systemImage: String,
Expand All @@ -227,6 +294,13 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
)
}

/// Creates a button with a specified role that generates its label from a string and a system image and an image resource.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - systemImage: The name of the image resource to lookup.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user interacts with the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand All @@ -247,6 +321,13 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {

@available(iOS 17.0, macOS 14.0, macCatalyst 17.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
/// Creates a button with a specified role that generates its label from a localized string key and an image resource.
/// - Parameters:
/// - titleKey: The key for the button's localized title, that describes the purpose of the button's `action`.
/// - image: The image resource to lookup.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user triggers the button.
public init(
_ titleKey: LocalizedStringKey,
image: ImageResource,
Expand All @@ -263,6 +344,13 @@ extension AsyncButton where Label == SwiftUI.Label<Text, Image> {
)
}

/// Creates a button with a specified role that generates its label from a string and an image resource.
/// - Parameters:
/// - title: A string that describes the purpose of the button's `action`.
/// - image: The image resource to lookup.
/// - role: An optional semantic role describing the button. A value of `nil` means that the button doesn't have an assigned role.
/// - priority: The task priority to use when creating the asynchronous task. The default priority is `userInitiated`.
/// - action: The action to perform when the user interacts with the button.
@_disfavoredOverload
public init<S>(
_ title: S,
Expand Down