diff --git a/.swift-format b/.swift-format index 7e8ae739..57e3fbbe 100644 --- a/.swift-format +++ b/.swift-format @@ -25,7 +25,7 @@ ] }, "rules" : { - "AllPublicDeclarationsHaveDocumentation" : false, + "AllPublicDeclarationsHaveDocumentation" : true, "AlwaysUseLiteralForEmptyCollectionInit" : false, "AlwaysUseLowerCamelCase" : false, "AmbiguousTrailingClosureOverload" : true, diff --git a/Sources/InMemoryTracing/InMemoryTracer.swift b/Sources/InMemoryTracing/InMemoryTracer.swift index 6c1fb632..690209c1 100644 --- a/Sources/InMemoryTracing/InMemoryTracer.swift +++ b/Sources/InMemoryTracing/InMemoryTracer.swift @@ -27,9 +27,12 @@ import Tracing /// ``popFinishedSpans()`` or any of the `clear...` methods (such as ``clearFinishedSpans()``) public struct InMemoryTracer: Tracer { + /// The strategy for generating trace and span identifiers. public let idGenerator: IDGenerator + /// A Boolean value that indicates whether the tracer records injected values. public let recordInjections: Bool + /// A Boolean value that indicates whether the tracer records extracted values. public let recordExtractions: Bool struct State { diff --git a/Sources/Instrumentation/Locks.swift b/Sources/Instrumentation/Locks.swift index 72bc54be..60cb773b 100644 --- a/Sources/Instrumentation/Locks.swift +++ b/Sources/Instrumentation/Locks.swift @@ -194,10 +194,14 @@ extension ReadWriteLock { public final class LockedValueBox: @unchecked Sendable { private let lock = ReadWriteLock() private var value: Value + /// Creates a new locking instance for the value you provide. public init(_ value: Value) { self.value = value } + /// Provides access to the locked value with a writer lock for the duration of the closure that you provide. + /// - Parameter work: The closure that provides the value within a writer lock. + /// - Returns: The value that you return from the closure. public func withValue(_ work: (inout Value) throws -> R) rethrows -> R { try self.lock.withWriterLock { try work(&self.value) diff --git a/Sources/Instrumentation/NoOpInstrument.swift b/Sources/Instrumentation/NoOpInstrument.swift index 15dbe331..55e1a977 100644 --- a/Sources/Instrumentation/NoOpInstrument.swift +++ b/Sources/Instrumentation/NoOpInstrument.swift @@ -16,6 +16,7 @@ import ServiceContextModule /// A "no op" implementation of an Instrument. public struct NoOpInstrument: Instrument { + /// Creates a new no-op instrument. public init() {} /// Extract values from a service context and inject them into the given carrier using the provided injector. /// diff --git a/Sources/Tracing/Tracer.swift b/Sources/Tracing/Tracer.swift index 30baf6bb..14b0065a 100644 --- a/Sources/Tracing/Tracer.swift +++ b/Sources/Tracing/Tracer.swift @@ -346,22 +346,25 @@ public func withSpan( } } -@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// +/// @DeprecationSummary { +/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. +/// } +/// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - instant: The time instant at which the span started. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. /// - kind: The ``SpanKind`` of the new ``Span``. -/// - isolation: Defaulted parameter for inheriting isolation of calling actor. /// - function: The function name in which the span was started. /// - fileID: The `fileID` where the span was started. /// - line: The file line where the span was started. /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). +@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext public func withSpan( _ operationName: String, @@ -433,11 +436,13 @@ public func withSpan( } } -@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") -@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// +/// @DeprecationSummary { +/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. +/// } +/// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. @@ -448,6 +453,8 @@ public func withSpan( /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). +@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") +@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext public func withSpan( _ operationName: String, context: @autoclosure () -> ServiceContext = .current ?? .topLevel, @@ -519,10 +526,13 @@ public func withSpan( } } -@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// +/// @DeprecationSummary { +/// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. +/// } +/// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. @@ -534,6 +544,7 @@ public func withSpan( /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). +@_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func withSpan( _ operationName: String, diff --git a/Sources/Tracing/TracerProtocol+Legacy.swift b/Sources/Tracing/TracerProtocol+Legacy.swift index ae08b882..f20e2189 100644 --- a/Sources/Tracing/TracerProtocol+Legacy.swift +++ b/Sources/Tracing/TracerProtocol+Legacy.swift @@ -338,22 +338,25 @@ extension LegacyTracer { } // swift-format-ignore: Spacing // fights with formatter - @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// + /// @DeprecationSummary { + /// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. + /// } + /// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - instant: the time instant at which the span started. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. /// - kind: The ``SpanKind`` of the new ``Span``. - /// - isolation: Defaulted parameter for inheriting isolation of calling actor. /// - function: The function name in which the span started. /// - fileID: The `fileID` where the span started. /// - line: The file line where the span started. /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). + @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") public func withAnySpan( _ operationName: String, at instant: @autoclosure () -> Instant, @@ -439,10 +442,13 @@ extension LegacyTracer { } // swift-format-ignore: Spacing // fights with formatter - @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// + /// @DeprecationSummary { + /// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. + /// } + /// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. @@ -453,6 +459,7 @@ extension LegacyTracer { /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). + @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") public func withAnySpan( _ operationName: String, context: @autoclosure () -> ServiceContext = .current ?? .topLevel, @@ -647,10 +654,13 @@ extension Tracer { } // swift-format-ignore: Spacing // fights with formatter - @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end when the operation completes, /// including recording the error in case the operation throws. /// + /// @DeprecationSummary { + /// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. + /// } + /// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. @@ -662,6 +672,7 @@ extension Tracer { /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). + @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") public func withAnySpan( _ operationName: String, at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now, diff --git a/Sources/Tracing/TracerProtocol.swift b/Sources/Tracing/TracerProtocol.swift index 1d4f045a..cf7e27e2 100644 --- a/Sources/Tracing/TracerProtocol.swift +++ b/Sources/Tracing/TracerProtocol.swift @@ -289,6 +289,12 @@ extension Tracer { } // swift-format-ignore: Spacing // fights with formatter + /// Start a new span and automatically end it when the operation completes, + /// including recording the error in case the operation throws. + /// + /// @DeprecationSummary { + /// Use ``withSpan(_:context:ofKind:isolation:function:file:line:_:)`` instead + /// } @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") public func withSpan( _ operationName: String, @@ -374,10 +380,13 @@ extension Tracer { } // swift-format-ignore: Spacing // fights with formatter - @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") /// Start a new span and automatically end it when the operation completes, /// including recording the error in case the operation throws. /// + /// @DeprecationSummary { + /// Use ``withSpan(_:at:context:ofKind:isolation:function:file:line:_:)`` instead. + /// } + /// /// - Parameters: /// - operationName: The name of the operation being traced. This may be a handler function, a database call, and so on. /// - context: The `ServiceContext` providing information on where to start the new ``Span``. @@ -389,6 +398,7 @@ extension Tracer { /// - operation: The operation that this span measures. /// - Returns: the value returned by `operation`. /// - Throws: the error the `operation` throws (if any). + @_disfavoredOverload @available(*, deprecated, message: "Prefer #isolation version of this API") public func withSpan( _ operationName: String, context: @autoclosure () -> ServiceContext = .current ?? .topLevel, diff --git a/Sources/_TracingBenchmarks/SpanAttributesDSLBenchmark.swift b/Sources/_TracingBenchmarks/SpanAttributesDSLBenchmark.swift index e93e8b29..9dc488f9 100644 --- a/Sources/_TracingBenchmarks/SpanAttributesDSLBenchmark.swift +++ b/Sources/_TracingBenchmarks/SpanAttributesDSLBenchmark.swift @@ -19,6 +19,7 @@ import _TracingBenchmarkTools // swift-format-ignore: DontRepeatTypeInStaticProperties @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext enum DSLBenchmarks { + /// Built-in span attribute DSL benchmarks public static let SpanAttributesDSLBenchmarks: [BenchmarkInfo] = [ BenchmarkInfo( name: "SpanAttributesDSLBenchmarks.000_bench_empty", diff --git a/Tests/TracingTests/DynamicTracepointTracerTests.swift b/Tests/TracingTests/DynamicTracepointTracerTests.swift index 1db601f8..f76a55ae 100644 --- a/Tests/TracingTests/DynamicTracepointTracerTests.swift +++ b/Tests/TracingTests/DynamicTracepointTracerTests.swift @@ -229,7 +229,7 @@ extension DynamicTracepointTestTracer { private let startTimestampNanosSinceEpoch: UInt64 private(set) var endTimestampNanosSinceEpoch: UInt64? - public var operationName: String + package var operationName: String private(set) var context: ServiceContext private(set) var isRecording: Bool = false diff --git a/Tests/TracingTests/SpanTests.swift b/Tests/TracingTests/SpanTests.swift index 713d94c9..58b81c37 100644 --- a/Tests/TracingTests/SpanTests.swift +++ b/Tests/TracingTests/SpanTests.swift @@ -300,7 +300,7 @@ extension SpanAttribute { } extension SpanAttributes { - public var sampleHttp: HTTPAttributes { + package var sampleHttp: HTTPAttributes { get { .init(attributes: self) } @@ -311,35 +311,35 @@ extension SpanAttributes { } @dynamicMemberLookup -public struct HTTPAttributes: SpanAttributeNamespace { - public var attributes: SpanAttributes - public init(attributes: SpanAttributes) { +package struct HTTPAttributes: SpanAttributeNamespace { + package var attributes: SpanAttributes + package init(attributes: SpanAttributes) { self.attributes = attributes } - public struct NestedSpanAttributes: NestedSpanAttributesProtocol { - public init() {} + package struct NestedSpanAttributes: NestedSpanAttributesProtocol { + package init() {} - public var statusCode: Key { + package var statusCode: Key { "http.status_code" } - public var codesArray: Key<[Int]> { + package var codesArray: Key<[Int]> { "http.codes_array" } - public var customType: Key { + package var customType: Key { "http.custom_value" } } } -public struct CustomAttributeValue: Equatable, Sendable, CustomStringConvertible, SpanAttributeConvertible { - public func toSpanAttribute() -> SpanAttribute { +package struct CustomAttributeValue: Equatable, Sendable, CustomStringConvertible, SpanAttributeConvertible { + package func toSpanAttribute() -> SpanAttribute { .stringConvertible(self) } - public var description: String { + package var description: String { "CustomAttributeValue()" } } diff --git a/Tests/TracingTests/TestTracer.swift b/Tests/TracingTests/TestTracer.swift index 580df93f..a8b27ee8 100644 --- a/Tests/TracingTests/TestTracer.swift +++ b/Tests/TracingTests/TestTracer.swift @@ -43,7 +43,7 @@ final class TestTracer: LegacyTracer { return span } - public func forceFlush() {} + package func forceFlush() {} func extract(_ carrier: Carrier, into context: inout ServiceContext, using extractor: Extract) where @@ -122,8 +122,8 @@ final class TestSpan: Span { private var status: SpanStatus? - public let startTimestampNanosSinceEpoch: UInt64 - public private(set) var endTimestampNanosSinceEpoch: UInt64? + package let startTimestampNanosSinceEpoch: UInt64 + package private(set) var endTimestampNanosSinceEpoch: UInt64? private(set) var recordedErrors: [(Error, SpanAttributes)] = [] diff --git a/Tests/TracingTests/TracedLockTests.swift b/Tests/TracingTests/TracedLockTests.swift index c2487d40..769cc61f 100644 --- a/Tests/TracingTests/TracedLockTests.swift +++ b/Tests/TracingTests/TracedLockTests.swift @@ -74,7 +74,7 @@ private final class TracedLockPrintlnTracer: LegacyTracer { ) } - public func forceFlush() {} + package func forceFlush() {} func inject( _ context: ServiceContext,