updates to Instrumentation module symbols

Author: heckj

Sources/Instrumentation/Instrument.swift

@@ -14,20 +14,25 @@
 
 import ServiceContextModule
 
-/// Conforming types are used to extract values from a specific `Carrier`.
+/// A type that allows tracing to extract values from an associated carrier.
+///
+/// The assocaited type, `Carrier`, is a service request such as an HTTP request,
+/// that has string values that can be extracted to provide information for a tracing span.
 public protocol Extractor: Sendable {
     /// The carrier to extract values from.
     associatedtype Carrier: Sendable
 
     /// Extract the value for the given key from the `Carrier`.
     ///
     /// - Parameters:
-    ///   - key: The key to be extracted.
+    ///   - key: The key to extract.
     ///   - carrier: The `Carrier` to extract from.
     func extract(key: String, from carrier: Carrier) -> String?
 }
 
-/// Conforming types are used to inject values into a specific `Carrier`.
+/// A type that allows you to inject values to an associated carrier.
+///
+/// The associated type, `Carrier`, is often a client or outgoing request into which values are inserted for tracing spans.
 public protocol Injector: Sendable {
     /// The carrier to inject values into.
     associatedtype Carrier: Sendable
@@ -41,10 +46,13 @@ public protocol Injector: Sendable {
     func inject(_ value: String, forKey key: String, into carrier: inout Carrier)
 }
 
-/// Conforming types are usually cross-cutting tools like tracers. They are agnostic of what specific `Carrier` is used
-/// to propagate metadata across boundaries, but instead just specify what values to use for which keys.
+/// A type that represents a cross-cutting tool, such as a tracer, that provides the a means to extract and inject service contexts into an associated carrier.
+///
+/// The types are agnostic of the specific `Carrier` used to propagate metadata across API boundaries.
+/// Instead they specify the values to use for which keys.
 public protocol Instrument: Sendable {
-    /// Extract values from a `Carrier` by using the given extractor and inject them into the given `ServiceContext`.
+    /// Extract values from a carrier, using the given extractor, and inject them into the provided service context.
+    ///
     /// It's quite common for `Instrument`s to come up with new values if they weren't passed along in the given `Carrier`.
     ///
     /// - Parameters:
@@ -54,12 +62,12 @@ public protocol Instrument: Sendable {
     func extract<Carrier, Extract>(_ carrier: Carrier, into context: inout ServiceContext, using extractor: Extract)
     where Extract: Extractor, Extract.Carrier == Carrier
 
-    /// Extract values from a `ServiceContext` and inject them into the given `Carrier` using the given ``Injector``.
+    /// Extract values from a service context and inject them into the given carrier using the provided injector.
     ///
     /// - Parameters:
-    ///   - context: The `ServiceContext` from which relevant information will be extracted.
-    ///   - carrier: The `Carrier` into which this information will be injected.
-    ///   - injector: The ``Injector`` used to inject extracted `ServiceContext` into the given `Carrier`.
+    ///   - context: The `ServiceContext` from which relevant information is extracted.
+    ///   - carrier: The `Carrier` into which this information is injected.
+    ///   - injector: The ``Injector`` to use to inject extracted `ServiceContext` into the given `Carrier`.
     func inject<Carrier, Inject>(_ context: ServiceContext, into carrier: inout Carrier, using injector: Inject)
     where Inject: Injector, Inject.Carrier == Carrier
 }

Sources/Instrumentation/InstrumentationSystem.swift

@@ -14,14 +14,20 @@
 
 import ServiceContextModule
 
-/// `InstrumentationSystem` is a global facility where the default cross-cutting tool can be configured.
+/// A global facility where the default cross-cutting tool can be configured.
+///
 /// It is set up just once in a given program to select the desired ``Instrument`` implementation.
 ///
-/// # Bootstrap multiple Instruments
+/// ###  Bootstrap multiple Instruments
 /// If you need to use more that one cross-cutting tool you can do so by using ``MultiplexInstrument``.
 ///
-/// # Access the Instrument
-/// ``instrument``: Returns whatever you passed to ``bootstrap(_:)`` as an ``Instrument``.
+/// ## Topics
+///
+/// ### Configuring the Instrument
+/// - ``bootstrap(_:)``
+///
+/// ### Accessing the Instrument
+/// - ``instrument``: Returns whatyou pass to ``bootstrap(_:)`` as an ``Instrument``.
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)  // for TaskLocal ServiceContext
 public enum InstrumentationSystem {
     /// Marked as @unchecked Sendable due to the synchronization being
@@ -73,7 +79,8 @@ public enum InstrumentationSystem {
     /// Globally select the desired ``Instrument`` implementation.
     ///
     /// - Parameter instrument: The ``Instrument`` you want to share globally within your system.
-    /// - Warning: Do not call this method more than once. This will lead to a crash.
+    ///
+    /// > Warning: Do not call this method more than once. This will lead to a crash.
     public static func bootstrap(_ instrument: Instrument) {
         self.shared.bootstrap(instrument)
     }
@@ -85,7 +92,7 @@ public enum InstrumentationSystem {
         self.shared.bootstrapInternal(instrument)
     }
 
-    /// Returns the globally configured ``Instrument``.
+    /// Returns the globally configured instrument.
     ///
     /// Defaults to a no-op ``Instrument`` if ``bootstrap(_:)`` wasn't called before.
     public static var instrument: Instrument {

Sources/Instrumentation/Locks.swift

@@ -93,10 +93,10 @@ public final class ReadWriteLock {
 }
 
 extension ReadWriteLock {
-    /// Acquire the reader lock for the duration of the given block.
+    /// Acquire a reader lock for the duration of the given block.
     ///
     /// This convenience method should be preferred to `lock` and `unlock` in
-    /// most situations, as it ensures that the lock will be released regardless
+    /// most situations, as it ensures that the lock is released regardless
     /// of how `body` exits.
     ///
     /// - Parameter body: The block to execute while holding the lock.
@@ -110,10 +110,10 @@ extension ReadWriteLock {
         return try body()
     }
 
-    /// Acquire the writer lock for the duration of the given block.
+    /// Acquire a writer lock for the duration of the given block.
     ///
     /// This convenience method should be preferred to `lock` and `unlock` in
-    /// most situations, as it ensures that the lock will be released regardless
+    /// most situations, as it ensures that the lock is released regardless
     /// of how `body` exits.
     ///
     /// - Parameter body: The block to execute while holding the lock.
@@ -128,7 +128,7 @@ extension ReadWriteLock {
     }
 }
 
-/// A wrapper providing locked access to a value.
+/// A wrapper that provides locked access to a value.
 ///
 /// Marked as @unchecked Sendable due to the synchronization being
 /// performed manually using locks.

Sources/Instrumentation/MultiplexInstrument.swift

@@ -14,14 +14,15 @@
 
 import ServiceContextModule
 
-/// A pseudo-``Instrument`` that may be used to instrument using multiple other ``Instrument``s across a
-/// common `ServiceContext`.
+/// A pseudo instrument to use to instrument using multiple instrumentss across a
+/// common service context.
 public struct MultiplexInstrument {
     private var instruments: [Instrument]
 
-    /// Create a ``MultiplexInstrument``.
-    ///
-    /// - Parameter instruments: An array of ``Instrument``s, each of which will be used to ``Instrument/inject(_:into:using:)`` or ``Instrument/extract(_:into:using:)``
+    /// Create a multiplex instrument.
+    /// 
+    /// - Parameter instruments: An array of ``Instrument``, each of which the tracer uses to
+    /// ``Instrument/inject(_:into:using:)`` or ``Instrument/extract(_:into:using:)``
     /// through the same `ServiceContext`.
     public init(_ instruments: [Instrument]) {
         self.instruments = instruments
@@ -35,11 +36,22 @@ extension MultiplexInstrument {
 }
 
 extension MultiplexInstrument: Instrument {
+    /// Extract values from a service context and inject them into the given carrier using the provided injector.
+    ///
+    /// - Parameters:
+    ///   - context: The `ServiceContext` from which relevant information is extracted.
+    ///   - carrier: The `Carrier` into which this information is injected.
+    ///   - injector: The ``Injector`` to use to inject extracted `ServiceContext` into the given `Carrier`.
     public func inject<Carrier, Inject>(_ context: ServiceContext, into carrier: inout Carrier, using injector: Inject)
     where Inject: Injector, Carrier == Inject.Carrier {
         for instrument in self.instruments { instrument.inject(context, into: &carrier, using: injector) }
     }
 
+    /// Extract values from a carrier, using the given extractor, and inject them into the provided service context.
+    /// - Parameters:
+    ///   - carrier: The `Carrier` that was used to propagate values across boundaries.
+    ///   - context: The `ServiceContext` into which these values should be injected.
+    ///   - extractor: The ``Extractor`` that extracts values from the given `Carrier`.
     public func extract<Carrier, Extract>(
         _ carrier: Carrier,
         into context: inout ServiceContext,

Sources/Instrumentation/NoOpInstrument.swift

@@ -14,7 +14,7 @@
 
 import ServiceContextModule
 
-/// A "no op" implementation of an ``Instrument``.
+/// A "no op" implementation of an Instrument.
 public struct NoOpInstrument: Instrument {
     public init() {}