apple · yim-lee · Aug 10, 2022 · Aug 10, 2022 · Aug 10, 2022 · Aug 10, 2022
diff --git a/Package.swift b/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.2
+// swift-tools-version:5.6
 import PackageDescription
 
 let package = Package(
@@ -9,6 +9,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         // ==== --------------------------------------------------------------------------------------------------------
@@ -46,7 +47,7 @@ let package = Package(
         // ==== --------------------------------------------------------------------------------------------------------
         // MARK: Performance / Benchmarks
 
-        .target(
+        .executableTarget(
             name: "_TracingBenchmarks",
             dependencies: [
                 .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
@@ -56,7 +57,8 @@ let package = Package(
         ),
         .target(
             name: "_TracingBenchmarkTools",
-            dependencies: []
+            dependencies: [],
+            exclude: ["README_SWIFT.md"]
         ),
     ]
 )
diff --git a/[email protected] b/[email protected]
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/[email protected] b/[email protected]
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/[email protected] b/[email protected]
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/[email protected] b/[email protected]
@@ -0,0 +1,62 @@
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "swift-distributed-tracing",
+    products: [
+        .library(name: "Instrumentation", targets: ["Instrumentation"]),
+        .library(name: "Tracing", targets: ["Tracing"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-distributed-tracing-baggage.git", .upToNextMinor(from: "0.3.0")),
+    ],
+    targets: [
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Instrumentation
+
+        .target(
+            name: "Instrumentation",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+            ]
+        ),
+        .testTarget(
+            name: "InstrumentationTests",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Tracing
+
+        .target(
+            name: "Tracing",
+            dependencies: [
+                .target(name: "Instrumentation"),
+            ]
+        ),
+        .testTarget(
+            name: "TracingTests",
+            dependencies: [
+                .target(name: "Tracing"),
+            ]
+        ),
+
+        // ==== --------------------------------------------------------------------------------------------------------
+        // MARK: Performance / Benchmarks
+
+        .target(
+            name: "_TracingBenchmarks",
+            dependencies: [
+                .product(name: "InstrumentationBaggage", package: "swift-distributed-tracing-baggage"),
+                .target(name: "Tracing"),
+                .target(name: "_TracingBenchmarkTools"),
+            ]
+        ),
+        .target(
+            name: "_TracingBenchmarkTools",
+            dependencies: []
+        ),
+    ]
+)
diff --git a/README.md b/README.md
@@ -226,9 +226,9 @@ While this is verbose, this is only the low-level building blocks that this libr
 
 > Eventually convenience wrappers will be provided, automatically wrapping future types etc. We welcome such contributions, but likely they should live in `swift-distributed-tracing-extras`.
 
-Once a system, or multiple systems have been instrumented, a Tracer been selected and your application runs and emits some trace information, you will be able to inspect how your application is behaving by looking at one of the various trace UIs, such as e.g. Zipkin:
+Once a system, or multiple systems have been instrumented, a Tracer has been selected and your application runs and emits some trace information, you will be able to inspect how your application is behaving by looking at one of the various trace UIs, such as e.g. Zipkin:
 
-![Simple example trace in Zipkin Web UI](images/zipkin_trace.png)
+![Simple example trace in Zipkin Web UI](Sources/Tracing/Docs.docc/Resources/zipkin_trace.png)
 
 ### More examples
 

diff --git a/Sources/Instrumentation/Instrument.swift b/Sources/Instrumentation/Instrument.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift Distributed Tracing open source project
 //
-// Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
+// Copyright (c) 2020-2022 Apple Inc. and the Swift Distributed Tracing project
 // authors
 // Licensed under Apache License v2.0
 //
@@ -44,22 +44,22 @@ public protocol Injector {
 /// 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.
 public protocol Instrument {
-    /// Extract values from a `Carrier` by using the given extractor and inject them into the given `BaggageContext`.
+    /// 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`.
+    ///   - extractor: The ``Extractor`` that extracts values from the given `Carrier`.
     func extract<Carrier, Extract>(_ carrier: Carrier, into baggage: inout Baggage, using extractor: Extract)
         where Extract: Extractor, Extract.Carrier == Carrier
 
-    /// Inject values from a `BaggageContext` and inject them into the given `Carrier` using the given `Injector`.
+    /// Extract 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 `BaggageContext` into the given `Carrier`.
+    ///   - injector: The ``Injector`` used to inject extracted `Baggage` into the given `Carrier`.
     func inject<Carrier, Inject>(_ baggage: Baggage, into carrier: inout Carrier, using injector: Inject)
         where Inject: Injector, Inject.Carrier == Carrier
 }
diff --git a/Sources/Instrumentation/InstrumentationSystem.swift b/Sources/Instrumentation/InstrumentationSystem.swift
@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift Distributed Tracing open source project
 //
-// Copyright (c) 2020-2021 Apple Inc. and the Swift Distributed Tracing project
+// Copyright (c) 2020-2022 Apple Inc. and the Swift Distributed Tracing project
 // authors
 // Licensed under Apache License v2.0
 //
@@ -15,21 +15,21 @@
 import InstrumentationBaggage
 
 /// `InstrumentationSystem` is 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.
+/// It is set up just once in a given program to select the desired ``Instrument`` implementation.
 ///
 /// # Bootstrap multiple Instruments
-/// If you need to use more that one cross-cutting tool you can do so by using `MultiplexInstrument`.
+/// If you need to use more that one cross-cutting tool you can do so by using ``MultiplexInstrument``.
 ///
 /// # Access the Instrument
-/// `InstrumentationSystem.instrument`: Returns whatever you passed to `.bootstrap` as an `Instrument`.
+/// ``instrument``: Returns whatever you passed to ``bootstrap(_:)`` as an ``Instrument``.
 public enum InstrumentationSystem {
     private static let lock = ReadWriteLock()
     private static var _instrument: Instrument = NoOpInstrument()
     private static var isInitialized = false
 
-    /// Globally select the desired `Instrument` implementation.
+    /// Globally select the desired ``Instrument`` implementation.
     ///
-    /// - Parameter instrument: The `Instrument` you want to share globally within your system.
+    /// - 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.
     public static func bootstrap(_ instrument: Instrument) {
         self.lock.withWriterLock {
@@ -44,18 +44,18 @@ public enum InstrumentationSystem {
         }
     }
 
-    /// For testing scenarios one may want to set instruments multiple times, rather than the set-once semantics enforced by `bootstrap()`.
+    /// For testing scenarios one may want to set instruments multiple times, rather than the set-once semantics enforced by ``bootstrap(_:)``.
     ///
-    /// - Parameter instrument: the instrument to boostrap the system with, if `nil` the `NoOpInstrument` is bootstrapped.
+    /// - Parameter instrument: the instrument to boostrap the system with, if `nil` the ``NoOpInstrument`` is bootstrapped.
     internal static func bootstrapInternal(_ instrument: Instrument?) {
         self.lock.withWriterLock {
             self._instrument = instrument ?? NoOpInstrument()
         }
     }
 
-    /// Returns the globally configured `Instrument`.
+    /// Returns the globally configured ``Instrument``.
     ///
-    /// Defaults to a no-op `Instrument` if `boostrap` wasn't called before.
+    /// Defaults to a no-op ``Instrument`` if ``bootstrap(_:)`` wasn't called before.
     public static var instrument: Instrument {
         self.lock.withReaderLock { self._instrument }
     }