Skip to content

Commit 6bdc0d2

Browse files
czechboy0czechboy0
authored
Label closure parameters in public APIs (#82)
### Motivation Fixes #21. Follows https://www.swift.org/documentation/api-design-guidelines/#special-instructions. ### Modifications Added a closure parameter to all the public APIs. ### Result Better documented API. ### Test Plan Tests pass.
1 parent 7819bf9 commit 6bdc0d2

15 files changed

+83
-78
lines changed

‎Sources/Configuration/ConfigProvider.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ public protocol ConfigProvider: Sendable {
101101
forKey key: AbsoluteConfigKey,
102102
type: ConfigType,
103103
updatesHandler: (
104-
ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
104+
_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
105105
) async throws -> Return
106106
) async throws -> Return
107107

@@ -129,7 +129,7 @@ public protocol ConfigProvider: Sendable {
129129
/// - Throws: Provider-specific errors or errors thrown by the handler closure.
130130
/// - Returns: The value returned by the closure.
131131
func watchSnapshot<Return: ~Copyable>(
132-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
132+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
133133
) async throws -> Return
134134
}
135135

‎Sources/Configuration/ConfigProviderHelpers.swift‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ extension ConfigProvider {
3030
/// func watchValue(
3131
/// forKey: AbsoluteConfigKey,
3232
/// type: ConfigType,
33-
/// updatesHandler: (ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Void
33+
/// updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Void
3434
/// ) async throws {
3535
/// try await watchValueFromValue(forKey: key, type: type, updatesHandler: updatesHandler)
3636
/// }
@@ -47,7 +47,7 @@ extension ConfigProvider {
4747
forKey key: AbsoluteConfigKey,
4848
type: ConfigType,
4949
updatesHandler: (
50-
ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
50+
_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
5151
) async throws -> Return
5252
) async throws -> Return
5353
{
@@ -76,7 +76,7 @@ extension ConfigProvider {
7676
///
7777
/// ```swift
7878
/// func watchSnapshot(
79-
/// updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Void
79+
/// updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Void
8080
/// ) async throws {
8181
/// try await watchSnapshotFromSnapshot(updatesHandler)
8282
/// }
@@ -86,7 +86,7 @@ extension ConfigProvider {
8686
/// - Returns: The value returned by the handler closure.
8787
/// - Throws: Provider-specific errors or errors thrown by the handler.
8888
nonisolated(nonsending) public func watchSnapshotFromSnapshot<Return: ~Copyable>(
89-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
89+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
9090
) async throws -> Return {
9191
let (stream, continuation) = AsyncStream<any ConfigSnapshot>
9292
.makeStream(bufferingPolicy: .bufferingNewest(1))

‎Sources/Configuration/ConfigReader+methods.swift‎

Lines changed: 42 additions & 42 deletions
Large diffs are not rendered by default.

‎Sources/Configuration/ConfigReader+methods.swift.gyb‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -703,7 +703,7 @@ extension ConfigReader {
703703
isSecret: Bool = false,
704704
fileID: String = #fileID,
705705
line: UInt = #line,
706-
updatesHandler: (ConfigUpdatesAsyncSequence<${primitive_type["type"]}?, Never>) async throws -> Return
706+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<${primitive_type["type"]}?, Never>) async throws -> Return
707707
) async throws -> Return {
708708
try await watchValue(
709709
forKey: key,
@@ -747,7 +747,7 @@ extension ConfigReader {
747747
default defaultValue: ${primitive_type["type"]},
748748
fileID: String = #fileID,
749749
line: UInt = #line,
750-
updatesHandler: (ConfigUpdatesAsyncSequence<${primitive_type["type"]}, Never>) async throws -> Return
750+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<${primitive_type["type"]}, Never>) async throws -> Return
751751
) async throws -> Return {
752752
try await watchValue(
753753
forKey: key,
@@ -790,7 +790,7 @@ extension ConfigReader {
790790
isSecret: Bool = false,
791791
fileID: String = #fileID,
792792
line: UInt = #line,
793-
updatesHandler: (ConfigUpdatesAsyncSequence<${primitive_type["type"]}, any Error>) async throws -> Return
793+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<${primitive_type["type"]}, any Error>) async throws -> Return
794794
) async throws -> Return {
795795
try await watchRequiredValue(
796796
forKey: key,
@@ -840,7 +840,7 @@ extension ConfigReader {
840840
isSecret: Bool = false,
841841
fileID: String = #fileID,
842842
line: UInt = #line,
843-
updatesHandler: (ConfigUpdatesAsyncSequence<Value?, Never>) async throws -> Return
843+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Value?, Never>) async throws -> Return
844844
) async throws -> Return {
845845
try await watchValue(
846846
forKey: key,
@@ -886,7 +886,7 @@ extension ConfigReader {
886886
default defaultValue: Value,
887887
fileID: String = #fileID,
888888
line: UInt = #line,
889-
updatesHandler: (ConfigUpdatesAsyncSequence<Value, Never>) async throws -> Return
889+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Value, Never>) async throws -> Return
890890
) async throws -> Return {
891891
try await watchValue(
892892
forKey: key,
@@ -931,7 +931,7 @@ extension ConfigReader {
931931
isSecret: Bool = false,
932932
fileID: String = #fileID,
933933
line: UInt = #line,
934-
updatesHandler: (ConfigUpdatesAsyncSequence<Value, any Error>) async throws -> Return
934+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Value, any Error>) async throws -> Return
935935
) async throws -> Return {
936936
try await watchRequiredValue(
937937
forKey: key,
@@ -979,7 +979,7 @@ extension ConfigReader {
979979
isSecret: Bool = false,
980980
fileID: String = #fileID,
981981
line: UInt = #line,
982-
updatesHandler: (ConfigUpdatesAsyncSequence<[Value]?, Never>) async throws -> Return
982+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<[Value]?, Never>) async throws -> Return
983983
) async throws -> Return {
984984
try await watchValue(
985985
forKey: key,
@@ -1025,7 +1025,7 @@ extension ConfigReader {
10251025
default defaultValue: [Value],
10261026
fileID: String = #fileID,
10271027
line: UInt = #line,
1028-
updatesHandler: (ConfigUpdatesAsyncSequence<[Value], Never>) async throws -> Return
1028+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<[Value], Never>) async throws -> Return
10291029
) async throws -> Return {
10301030
try await watchValue(
10311031
forKey: key,
@@ -1070,7 +1070,7 @@ extension ConfigReader {
10701070
isSecret: Bool = false,
10711071
fileID: String = #fileID,
10721072
line: UInt = #line,
1073-
updatesHandler: (ConfigUpdatesAsyncSequence<[Value], any Error>) async throws -> Return
1073+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<[Value], any Error>) async throws -> Return
10741074
) async throws -> Return {
10751075
try await watchRequiredValue(
10761076
forKey: key,

‎Sources/Configuration/ConfigSnapshotReader.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ extension ConfigReader {
281281
public func watchSnapshot<Return: ~Copyable>(
282282
fileID: String = #fileID,
283283
line: UInt = #line,
284-
updatesHandler: (ConfigUpdatesAsyncSequence<ConfigSnapshotReader, Never>) async throws -> Return
284+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<ConfigSnapshotReader, Never>) async throws -> Return
285285
) async throws -> Return {
286286
try await provider.watchSnapshot { updates in
287287
try await updatesHandler(

‎Sources/Configuration/Providers/CLI/CommandLineArgumentsProvider.swift‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,8 @@ extension CommandLineArgumentsProvider: ConfigProvider {
153153
public func watchValue<Return: ~Copyable>(
154154
forKey key: AbsoluteConfigKey,
155155
type: ConfigType,
156-
updatesHandler: (ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Return
156+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws ->
157+
Return
157158
) async throws -> Return {
158159
try await watchValueFromValue(forKey: key, type: type, updatesHandler: updatesHandler)
159160
}
@@ -165,7 +166,7 @@ extension CommandLineArgumentsProvider: ConfigProvider {
165166

166167
// swift-format-ignore: AllPublicDeclarationsHaveDocumentation
167168
public func watchSnapshot<Return: ~Copyable>(
168-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
169+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
169170
) async throws -> Return {
170171
try await watchSnapshotFromSnapshot(updatesHandler: updatesHandler)
171172
}

‎Sources/Configuration/Providers/EnvironmentVariables/EnvironmentVariablesProvider.swift‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -494,7 +494,8 @@ extension EnvironmentVariablesProvider: ConfigProvider {
494494
public func watchValue<Return: ~Copyable>(
495495
forKey key: AbsoluteConfigKey,
496496
type: ConfigType,
497-
updatesHandler: (ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Return
497+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws ->
498+
Return
498499
) async throws -> Return {
499500
try await watchValueFromValue(forKey: key, type: type, updatesHandler: updatesHandler)
500501
}
@@ -506,7 +507,7 @@ extension EnvironmentVariablesProvider: ConfigProvider {
506507

507508
// swift-format-ignore: AllPublicDeclarationsHaveDocumentation
508509
public func watchSnapshot<Return: ~Copyable>(
509-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
510+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
510511
) async throws -> Return {
511512
try await watchSnapshotFromSnapshot(updatesHandler: updatesHandler)
512513
}

‎Sources/Configuration/Providers/Files/DirectoryFilesProvider.swift‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -453,7 +453,8 @@ extension DirectoryFilesProvider: ConfigProvider {
453453
public func watchValue<Return: ~Copyable>(
454454
forKey key: AbsoluteConfigKey,
455455
type: ConfigType,
456-
updatesHandler: (ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Return
456+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws ->
457+
Return
457458
) async throws -> Return {
458459
try await watchValueFromValue(forKey: key, type: type, updatesHandler: updatesHandler)
459460
}
@@ -465,7 +466,7 @@ extension DirectoryFilesProvider: ConfigProvider {
465466

466467
// swift-format-ignore: AllPublicDeclarationsHaveDocumentation
467468
public func watchSnapshot<Return: ~Copyable>(
468-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
469+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
469470
) async throws -> Return {
470471
try await watchSnapshotFromSnapshot(updatesHandler: updatesHandler)
471472
}

‎Sources/Configuration/Providers/Files/FileProvider.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ extension FileProvider: ConfigProvider {
235235

236236
// swift-format-ignore: AllPublicDeclarationsHaveDocumentation
237237
public func watchSnapshot<Return: ~Copyable>(
238-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
238+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
239239
) async throws -> Return {
240240
try await watchSnapshotFromSnapshot(updatesHandler: updatesHandler)
241241
}
@@ -245,7 +245,7 @@ extension FileProvider: ConfigProvider {
245245
forKey key: AbsoluteConfigKey,
246246
type: ConfigType,
247247
updatesHandler: (
248-
ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
248+
_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>
249249
) async throws -> Return
250250
) async throws -> Return {
251251
try await watchValueFromValue(forKey: key, type: type, updatesHandler: updatesHandler)

‎Sources/Configuration/Providers/Files/ReloadingFileProvider.swift‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -614,7 +614,8 @@ extension ReloadingFileProvider: ConfigProvider {
614614
public func watchValue<Return: ~Copyable>(
615615
forKey key: AbsoluteConfigKey,
616616
type: ConfigType,
617-
updatesHandler: (ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws -> Return
617+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<Result<LookupResult, any Error>, Never>) async throws ->
618+
Return
618619
) async throws -> Return {
619620
let (stream, continuation) = AsyncStream<Result<LookupResult, any Error>>
620621
.makeStream(bufferingPolicy: .bufferingNewest(1))
@@ -647,7 +648,7 @@ extension ReloadingFileProvider: ConfigProvider {
647648

648649
// swift-format-ignore: AllPublicDeclarationsHaveDocumentation
649650
public func watchSnapshot<Return: ~Copyable>(
650-
updatesHandler: (ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
651+
updatesHandler: (_ updates: ConfigUpdatesAsyncSequence<any ConfigSnapshot, Never>) async throws -> Return
651652
) async throws -> Return {
652653
let (stream, continuation) = AsyncStream<AnySnapshot>.makeStream(bufferingPolicy: .bufferingNewest(1))
653654
let id = UUID()

0 commit comments

Comments
 (0)