Skip to content

Commit 4b5227d

Browse files
ra1028ra1028
authored
Improve API docs format for modifiers (#200)
1 parent ea74c08 commit 4b5227d

File tree

6 files changed

+130
-53
lines changed

6 files changed

+130
-53
lines changed

‎Sources/Atoms/Modifier/AnimationModifier.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ public extension Atom {
55
///
66
/// Note that this modifier does nothing when being watched by other atoms.
77
///
8+
/// ## Example
9+
///
810
/// ```swift
911
/// struct TextAtom: ValueAtom, Hashable {
1012
/// func value(context: Context) -> String {

‎Sources/Atoms/Modifier/ChangesModifier.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
public extension Atom where Produced: Equatable {
22
/// Prevents the atom from updating its downstream when its new value is equivalent to old value.
33
///
4+
/// ## Example
5+
///
46
/// ```swift
57
/// struct FlagAtom: StateAtom, Hashable {
68
/// func defaultValue(context: Context) -> Bool {

‎Sources/Atoms/Modifier/ChangesOfModifier.swift‎

Lines changed: 50 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,61 @@
11
public extension Atom {
2-
/// Derives a partial property with the specified key path from the original atom and prevent it
3-
/// from updating its downstream when its new value is equivalent to old value.
4-
///
5-
/// ```swift
6-
/// struct IntAtom: ValueAtom, Hashable {
7-
/// func value(context: Context) -> Int {
8-
/// 12345
9-
/// }
10-
/// }
11-
///
12-
/// struct ExampleView: View {
13-
/// @Watch(IntAtom().changes(of: \.description))
14-
/// var description
15-
///
16-
/// var body: some View {
17-
/// Text(description)
18-
/// }
19-
/// }
20-
/// ```
21-
///
22-
/// - Parameter keyPath: A key path for the property of the original atom value.
23-
///
24-
/// - Returns: An atom that provides the partial property of the original atom value.
252
#if hasFeature(InferSendableFromCaptures)
3+
/// Derives a partial property with the specified key path from the original atom and prevent it
4+
/// from updating its downstream when its new value is equivalent to old value.
5+
///
6+
/// ## Example
7+
///
8+
/// ```swift
9+
/// struct IntAtom: ValueAtom, Hashable {
10+
/// func value(context: Context) -> Int {
11+
/// 12345
12+
/// }
13+
/// }
14+
///
15+
/// struct ExampleView: View {
16+
/// @Watch(IntAtom().changes(of: \.description))
17+
/// var description
18+
///
19+
/// var body: some View {
20+
/// Text(description)
21+
/// }
22+
/// }
23+
/// ```
24+
///
25+
/// - Parameter keyPath: A key path for the property of the original atom value.
26+
///
27+
/// - Returns: An atom that provides the partial property of the original atom value.
2628
func changes<T: Equatable>(
2729
of keyPath: any KeyPath<Produced, T> & Sendable
2830
) -> ModifiedAtom<Self, ChangesOfModifier<Produced, T>> {
2931
modifier(ChangesOfModifier(keyPath: keyPath))
3032
}
3133
#else
34+
/// Derives a partial property with the specified key path from the original atom and prevent it
35+
/// from updating its downstream when its new value is equivalent to old value.
36+
///
37+
/// ## Example
38+
///
39+
/// ```swift
40+
/// struct IntAtom: ValueAtom, Hashable {
41+
/// func value(context: Context) -> Int {
42+
/// 12345
43+
/// }
44+
/// }
45+
///
46+
/// struct ExampleView: View {
47+
/// @Watch(IntAtom().changes(of: \.description))
48+
/// var description
49+
///
50+
/// var body: some View {
51+
/// Text(description)
52+
/// }
53+
/// }
54+
/// ```
55+
///
56+
/// - Parameter keyPath: A key path for the property of the original atom value.
57+
///
58+
/// - Returns: An atom that provides the partial property of the original atom value.
3259
func changes<T: Equatable>(
3360
of keyPath: KeyPath<Produced, T>
3461
) -> ModifiedAtom<Self, ChangesOfModifier<Produced, T>> {

‎Sources/Atoms/Modifier/LatestModifier.swift‎

Lines changed: 70 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,79 @@
11
public extension Atom {
2-
/// Provides the latest value that matches the specified condition instead of the current value.
3-
///
4-
/// ```swift
5-
/// struct Item {
6-
/// let id: Int
7-
/// let isValid: Bool
8-
/// }
9-
///
10-
/// struct ItemAtom: StateAtom, Hashable {
11-
/// func defaultValue(context: Context) -> Item {
12-
/// Item(id: 0, isValid: false)
13-
/// }
14-
/// }
15-
///
16-
/// struct ExampleView: View {
17-
/// @Watch(ItemAtom())
18-
/// var currentItem
19-
///
20-
/// @Watch(ItemAtom().latest(\.isValid))
21-
/// var latestValidItem
22-
///
23-
/// var body: some View {
24-
/// VStack {
25-
/// Text("Current ID: \(currentItem.id)")
26-
/// Text("Latest Valid ID: \(latestValidItem?.id ?? 0)")
27-
/// }
28-
/// }
29-
/// }
30-
/// ```
31-
///
322
#if hasFeature(InferSendableFromCaptures)
3+
/// Provides the latest value that matches the specified condition instead of the current value.
4+
///
5+
/// ## Example
6+
///
7+
/// ```swift
8+
/// struct Item {
9+
/// let id: Int
10+
/// let isValid: Bool
11+
/// }
12+
///
13+
/// struct ItemAtom: StateAtom, Hashable {
14+
/// func defaultValue(context: Context) -> Item {
15+
/// Item(id: 0, isValid: false)
16+
/// }
17+
/// }
18+
///
19+
/// struct ExampleView: View {
20+
/// @Watch(ItemAtom())
21+
/// var currentItem
22+
///
23+
/// @Watch(ItemAtom().latest(\.isValid))
24+
/// var latestValidItem
25+
///
26+
/// var body: some View {
27+
/// VStack {
28+
/// Text("Current ID: \(currentItem.id)")
29+
/// Text("Latest Valid ID: \(latestValidItem?.id ?? 0)")
30+
/// }
31+
/// }
32+
/// }
33+
/// ```
34+
///
35+
/// - Parameter keyPath: A key path to a `Bool` property of the atom value that determines whether the value should be retained as the latest.
36+
///
37+
/// - Returns: An atom that provides the latest value that matches the specified condition, or `nil` if no value has matched yet.
3338
func latest(_ keyPath: any KeyPath<Produced, Bool> & Sendable) -> ModifiedAtom<Self, LatestModifier<Produced>> {
3439
modifier(LatestModifier(keyPath: keyPath))
3540
}
3641
#else
42+
/// Provides the latest value that matches the specified condition instead of the current value.
43+
///
44+
/// ## Example
45+
///
46+
/// ```swift
47+
/// struct Item {
48+
/// let id: Int
49+
/// let isValid: Bool
50+
/// }
51+
///
52+
/// struct ItemAtom: StateAtom, Hashable {
53+
/// func defaultValue(context: Context) -> Item {
54+
/// Item(id: 0, isValid: false)
55+
/// }
56+
/// }
57+
///
58+
/// struct ExampleView: View {
59+
/// @Watch(ItemAtom())
60+
/// var currentItem
61+
///
62+
/// @Watch(ItemAtom().latest(\.isValid))
63+
/// var latestValidItem
64+
///
65+
/// var body: some View {
66+
/// VStack {
67+
/// Text("Current ID: \(currentItem.id)")
68+
/// Text("Latest Valid ID: \(latestValidItem?.id ?? 0)")
69+
/// }
70+
/// }
71+
/// }
72+
/// ```
73+
///
74+
/// - Parameter keyPath: A key path to a `Bool` property of the atom value that determines whether the value should be retained as the latest.
75+
///
76+
/// - Returns: An atom that provides the latest value that matches the specified condition, or `nil` if no value has matched yet.
3777
func latest(_ keyPath: KeyPath<Produced, Bool>) -> ModifiedAtom<Self, LatestModifier<Produced>> {
3878
modifier(LatestModifier(keyPath: keyPath))
3979
}

‎Sources/Atoms/Modifier/PreviousModifier.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
public extension Atom {
22
/// Provides the previous value of the atom instead of the current value.
33
///
4+
/// ## Example
5+
///
46
/// ```swift
57
/// struct CounterAtom: StateAtom, Hashable {
68
/// func defaultValue(context: Context) -> Int {

‎Sources/Atoms/Modifier/TaskPhaseModifier.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ public extension TaskAtom {
22
/// Converts the `Task` that the original atom provides into ``AsyncPhase`` that
33
/// changes overtime.
44
///
5+
/// ## Example
6+
///
57
/// ```swift
68
/// struct AsyncIntAtom: TaskAtom, Hashable {
79
/// func value(context: Context) async -> Int {
@@ -35,6 +37,8 @@ public extension ThrowingTaskAtom {
3537
/// Converts the `Task` that the original atom provides into ``AsyncPhase`` that
3638
/// changes overtime.
3739
///
40+
/// ## Example
41+
///
3842
/// ```swift
3943
/// struct AsyncIntAtom: ThrowingTaskAtom, Hashable {
4044
/// func value(context: Context) async throws -> Int {

0 commit comments

Comments
 (0)