Skip to content

Commit 8d90b4d

Browse files
heckjheckj
committed
fixing doc layout to resolve swift-format lint concerns, and adding deprecation summary to redirect readers to correct API for deprecated versions
1 parent db35d03 commit 8d90b4d

File tree

8 files changed

+52
-9
lines changed

8 files changed

+52
-9
lines changed

‎.swift-format‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
]
2626
},
2727
"rules" : {
28-
"AllPublicDeclarationsHaveDocumentation" : false,
28+
"AllPublicDeclarationsHaveDocumentation" : true,
2929
"AlwaysUseLiteralForEmptyCollectionInit" : false,
3030
"AlwaysUseLowerCamelCase" : false,
3131
"AmbiguousTrailingClosureOverload" : true,

‎Sources/InMemoryTracing/InMemoryTracer.swift‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,12 @@ import Tracing
2727
/// ``popFinishedSpans()`` or any of the `clear...` methods (such as ``clearFinishedSpans()``)
2828
public struct InMemoryTracer: Tracer {
2929

30+
/// The strategy for generating trace and span identifiers.
3031
public let idGenerator: IDGenerator
3132

33+
/// A Boolean value that indicates whether the tracer records injected values.
3234
public let recordInjections: Bool
35+
/// A Boolean value that indicates whether the tracer records extracted values.
3336
public let recordExtractions: Bool
3437

3538
struct State {

‎Sources/Instrumentation/Locks.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,10 +194,14 @@ extension ReadWriteLock {
194194
public final class LockedValueBox<Value: Sendable>: @unchecked Sendable {
195195
private let lock = ReadWriteLock()
196196
private var value: Value
197+
/// Creates a new locking instance for the value you provide.
197198
public init(_ value: Value) {
198199
self.value = value
199200
}
200201

202+
/// Provides access to the locked value with a writer lock for the duration of the closure that you provide.
203+
/// - Parameter work: The closure that provides the value within a writer lock.
204+
/// - Returns: The value that you return from the closure.
201205
public func withValue<R>(_ work: (inout Value) throws -> R) rethrows -> R {
202206
try self.lock.withWriterLock {
203207
try work(&self.value)

‎Sources/Instrumentation/NoOpInstrument.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import ServiceContextModule
1616

1717
/// A "no op" implementation of an Instrument.
1818
public struct NoOpInstrument: Instrument {
19+
/// Creates a new no-op instrument.
1920
public init() {}
2021
/// Extract values from a service context and inject them into the given carrier using the provided injector.
2122
///

‎Sources/Tracing/Tracer.swift‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -346,10 +346,13 @@ public func withSpan<T, Instant: TracerInstant>(
346346
}
347347
}
348348

349-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
350349
/// Start a new span and automatically end when the operation completes,
351350
/// including recording the error in case the operation throws.
352351
///
352+
/// @DeprecationSummary {
353+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
354+
/// }
355+
///
353356
/// - Parameters:
354357
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
355358
/// - instant: The time instant at which the span started.
@@ -362,6 +365,7 @@ public func withSpan<T, Instant: TracerInstant>(
362365
/// - operation: The operation that this span measures.
363366
/// - Returns: the value returned by `operation`.
364367
/// - Throws: the error the `operation` throws (if any).
368+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
365369
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext
366370
public func withSpan<T, Instant: TracerInstant>(
367371
_ operationName: String,
@@ -433,11 +437,13 @@ public func withSpan<T>(
433437
}
434438
}
435439

436-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
437-
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext
438440
/// Start a new span and automatically end when the operation completes,
439441
/// including recording the error in case the operation throws.
440442
///
443+
/// @DeprecationSummary {
444+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
445+
/// }
446+
///
441447
/// - Parameters:
442448
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
443449
/// - context: The `ServiceContext` providing information on where to start the new ``Span``.
@@ -448,6 +454,8 @@ public func withSpan<T>(
448454
/// - operation: The operation that this span measures.
449455
/// - Returns: the value returned by `operation`.
450456
/// - Throws: the error the `operation` throws (if any).
457+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
458+
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext
451459
public func withSpan<T>(
452460
_ operationName: String,
453461
context: @autoclosure () -> ServiceContext = .current ?? .topLevel,
@@ -519,10 +527,13 @@ public func withSpan<T>(
519527
}
520528
}
521529

522-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
523530
/// Start a new span and automatically end when the operation completes,
524531
/// including recording the error in case the operation throws.
525532
///
533+
/// @DeprecationSummary {
534+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
535+
/// }
536+
///
526537
/// - Parameters:
527538
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
528539
/// - context: The `ServiceContext` providing information on where to start the new ``Span``.
@@ -534,6 +545,7 @@ public func withSpan<T>(
534545
/// - operation: The operation that this span measures.
535546
/// - Returns: the value returned by `operation`.
536547
/// - Throws: the error the `operation` throws (if any).
548+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
537549
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
538550
public func withSpan<T>(
539551
_ operationName: String,

‎Sources/Tracing/TracerProtocol+Legacy.swift‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -338,10 +338,13 @@ extension LegacyTracer {
338338
}
339339

340340
// swift-format-ignore: Spacing // fights with formatter
341-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
342341
/// Start a new span and automatically end when the operation completes,
343342
/// including recording the error in case the operation throws.
344343
///
344+
/// @DeprecationSummary {
345+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
346+
/// }
347+
///
345348
/// - Parameters:
346349
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
347350
/// - instant: the time instant at which the span started.
@@ -354,6 +357,7 @@ extension LegacyTracer {
354357
/// - operation: The operation that this span measures.
355358
/// - Returns: the value returned by `operation`.
356359
/// - Throws: the error the `operation` throws (if any).
360+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
357361
public func withAnySpan<T, Instant: TracerInstant>(
358362
_ operationName: String,
359363
at instant: @autoclosure () -> Instant,
@@ -439,10 +443,13 @@ extension LegacyTracer {
439443
}
440444

441445
// swift-format-ignore: Spacing // fights with formatter
442-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
443446
/// Start a new span and automatically end when the operation completes,
444447
/// including recording the error in case the operation throws.
445448
///
449+
/// @DeprecationSummary {
450+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
451+
/// }
452+
///
446453
/// - Parameters:
447454
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
448455
/// - context: The `ServiceContext` providing information on where to start the new ``Span``.
@@ -453,6 +460,7 @@ extension LegacyTracer {
453460
/// - operation: The operation that this span measures.
454461
/// - Returns: the value returned by `operation`.
455462
/// - Throws: the error the `operation` throws (if any).
463+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
456464
public func withAnySpan<T>(
457465
_ operationName: String,
458466
context: @autoclosure () -> ServiceContext = .current ?? .topLevel,
@@ -647,10 +655,13 @@ extension Tracer {
647655
}
648656

649657
// swift-format-ignore: Spacing // fights with formatter
650-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
651658
/// Start a new span and automatically end when the operation completes,
652659
/// including recording the error in case the operation throws.
653660
///
661+
/// @DeprecationSummary {
662+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
663+
/// }
664+
///
654665
/// - Parameters:
655666
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
656667
/// - context: The `ServiceContext` providing information on where to start the new ``Span``.
@@ -662,6 +673,7 @@ extension Tracer {
662673
/// - operation: The operation that this span measures.
663674
/// - Returns: the value returned by `operation`.
664675
/// - Throws: the error the `operation` throws (if any).
676+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
665677
public func withAnySpan<T>(
666678
_ operationName: String,
667679
at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now,

‎Sources/Tracing/TracerProtocol.swift‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,12 @@ extension Tracer {
289289
}
290290

291291
// swift-format-ignore: Spacing // fights with formatter
292+
/// Start a new span and automatically end it when the operation completes,
293+
/// including recording the error in case the operation throws.
294+
///
295+
/// @DeprecationSummary {
296+
/// Use ``withSpan(_:context:ofKind:isolation:function:file:line:_:)`` instead
297+
/// }
292298
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
293299
public func withSpan<T>(
294300
_ operationName: String,
@@ -374,10 +380,13 @@ extension Tracer {
374380
}
375381

376382
// swift-format-ignore: Spacing // fights with formatter
377-
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
378383
/// Start a new span and automatically end it when the operation completes,
379384
/// including recording the error in case the operation throws.
380385
///
386+
/// @DeprecationSummary {
387+
/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead.
388+
/// }
389+
///
381390
/// - Parameters:
382391
/// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on.
383392
/// - context: The `ServiceContext` providing information on where to start the new ``Span``.
@@ -389,6 +398,7 @@ extension Tracer {
389398
/// - operation: The operation that this span measures.
390399
/// - Returns: the value returned by `operation`.
391400
/// - Throws: the error the `operation` throws (if any).
401+
@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API")
392402
public func withSpan<T>(
393403
_ operationName: String,
394404
context: @autoclosure () -> ServiceContext = .current ?? .topLevel,

‎Sources/_TracingBenchmarks/SpanAttributesDSLBenchmark.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import _TracingBenchmarkTools
1919
// swift-format-ignore: DontRepeatTypeInStaticProperties
2020
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext
2121
enum DSLBenchmarks {
22+
/// Built-in span attribute DSL benchmarks
2223
public static let SpanAttributesDSLBenchmarks: [BenchmarkInfo] = [
2324
BenchmarkInfo(
2425
name: "SpanAttributesDSLBenchmarks.000_bench_empty",

0 commit comments

Comments
 (0)