fixing docs (#198)

- update docs ordering to resolve swift-format lint concerns
- adding deprecation summary to redirect readers to correct API for
deprecated versions
- updating .swift-format to preserve checking going forward

resolves #182

Author: heckj

.swift-format

@@ -25,7 +25,7 @@
     ]
   },
   "rules" : {
-    "AllPublicDeclarationsHaveDocumentation" : false,
+    "AllPublicDeclarationsHaveDocumentation" : true,
     "AlwaysUseLiteralForEmptyCollectionInit" : false,
     "AlwaysUseLowerCamelCase" : false,
     "AmbiguousTrailingClosureOverload" : true,

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 {

Sources/Instrumentation/Locks.swift

@@ -194,10 +194,14 @@ extension ReadWriteLock {
 public final class LockedValueBox<Value: Sendable>: @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<R>(_ work: (inout Value) throws -> R) rethrows -> R {
         try self.lock.withWriterLock {
             try work(&self.value)

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.
     ///

Sources/Tracing/Tracer.swift

@@ -346,22 +346,25 @@ public func withSpan<T, Instant: TracerInstant>(
     }
 }
 
-@_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<T, Instant: TracerInstant>(
     _ operationName: String,
@@ -433,11 +436,13 @@ public func withSpan<T>(
     }
 }
 
-@_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<T>(
 ///   - 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<T>(
     _ operationName: String,
     context: @autoclosure () -> ServiceContext = .current ?? .topLevel,
@@ -519,10 +526,13 @@ public func withSpan<T>(
     }
 }
 
-@_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<T>(
 ///   - 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<T>(
     _ operationName: String,

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<T, Instant: TracerInstant>(
         _ 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<T>(
         _ 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<T>(
         _ operationName: String,
         at instant: @autoclosure () -> some TracerInstant = DefaultTracerClock.now,

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<T>(
         _ 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<T>(
         _ operationName: String,
         context: @autoclosure () -> ServiceContext = .current ?? .topLevel,

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",

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
 

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<Int> {
+        package var statusCode: Key<Int> {
             "http.status_code"
         }
 
-        public var codesArray: Key<[Int]> {
+        package var codesArray: Key<[Int]> {
             "http.codes_array"
         }
 
-        public var customType: Key<CustomAttributeValue> {
+        package var customType: Key<CustomAttributeValue> {
             "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()"
     }
 }