+tracer,instrument provide static helper functions

Author: ktoso

Sources/Instrumentation/Instrument.swift

@@ -15,9 +15,40 @@
 import InstrumentationBaggage
 
 public enum Instrument {
+
+    /// Convenience to access the globally bootstrapped instrument on ``InstrumentationSystem``.
+    ///
+    /// Equivalent to ``InstrumentationSystem/instrument``.
     static var current: InstrumentProtocol {
         InstrumentationSystem.instrument
     }
+
+    /// Obtain the ``current`` instrument which was bootstrapped on the global ``InstrumentationSystem``,
+    /// and invoke ``InstrumentProtocol/extract(_:into:using:)`` on it.
+    ///
+    /// Extract values from a `Carrier` by using the given extractor and inject them into the given `Baggage`.
+    /// It's quite common for `Instrument`s to come up with new values if they weren't passed along in the given `Carrier`.
+    ///
+    /// - Parameters:
+    ///   - carrier: The `Carrier` that was used to propagate values across boundaries.
+    ///   - baggage: The `Baggage` into which these values should be injected.
+    ///   - extractor: The ``Extractor`` that extracts values from the given `Carrier`.
+    public static func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract) where Extract: Extractor, Extract.Carrier == Carrier {
+        Instrument.current.extract(carrier, into: &baggage, using: extractor)
+    }
+
+    /// Obtain the ``current`` instrument which was bootstrapped on the global ``InstrumentationSystem``,
+    /// and invoke ``InstrumentProtocol/extract(_:into:using:)`` on it.
+    ///
+    /// Take values from a `Baggage` and inject them into the given `Carrier` using the given ``Injector``.
+    ///
+    /// - Parameters:
+    ///   - baggage: The `Baggage` from which relevant information will be extracted.
+    ///   - carrier: The `Carrier` into which this information will be injected.
+    ///   - injector: The ``Injector`` used to inject extracted `Baggage` into the given `Carrier`.
+    public static func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject) where Inject: Injector, Inject.Carrier == Carrier {
+        Instrument.current.inject(baggage, into: &carrier, using: injector)
+    }
 }
 
 /// Conforming types are usually cross-cutting tools like tracers. They are agnostic of what specific `Carrier` is used
@@ -33,7 +64,7 @@ public protocol InstrumentProtocol {
     func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract)
         where Extract: Extractor, Extract.Carrier == Carrier
 
-    /// Extract values from a `Baggage` and inject them into the given `Carrier` using the given ``Injector``.
+    /// Take values from a `Baggage` and inject them into the given `Carrier` using the given ``Injector``.
     ///
     /// - Parameters:
     ///   - baggage: The `Baggage` from which relevant information will be extracted.

Sources/Tracing/Span.swift

@@ -19,7 +19,28 @@ import Dispatch
 /// with it. A `Span` can be created from a `Baggage` which contains span information, in which case this span should
 /// be considered as "child" of the previous span.
 ///
-/// Creating a `Span` is delegated to a ``Tracer`` and end users should never create them directly.
+/// Creating a `Span` is delegated to an implementation of ``TracerProtocol`` and end-users should never instantiate spans directly.
+/// Most commonly, a span is started using the `withSpan` API of a tracer, like this:
+///
+/// ```
+/// tracer.withSpan("working-on-\(thing)") { span in
+///     // ...
+/// }
+/// ```
+///
+/// Once started, a span contains its start time and additional metadata necessary for the tracing backend to handle e.g.
+/// further child spans.
+///
+/// ### Child Spans
+///
+///
+/// ## Manual lifetime management
+/// In some situations it may not be possible
+///
+/// > Warning: Generally spans should be started using the ``TracerProtocol/withSpan(_:ofKind:_:)-11n3y`` method,
+/// > however it may sometimes be necessary to use the alternate ``TracerProtocol/startSpan(_:baggage:ofKind:)`` API.
+/// > If the `startSpan` API is used to create a span, it must be explicitly ended using ``end()`` on *every* code-path
+/// > leading to the logical end of the span. Omitting to end a span or ending it twice is a programmer error.
 ///
 /// - SeeAlso: For more details refer to the [OpenTelemetry Specification: Span](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.7.0/specification/trace/api.md#span) which this type is compatible with.
 public protocol Span: AnyObject {
@@ -84,6 +105,7 @@ extension Span {
     }
 
     /// Adds a ``SpanLink`` between this `Span` and the given `Span`.
+    ///
     /// - Parameter other: The `Span` to link to.
     /// - Parameter attributes: The ``SpanAttributes`` describing this link. Defaults to no attributes.
     public func addLink(_ other: Span, attributes: SpanAttributes = [:]) {