update documentation references to fix broken reference links on SwiftPackageIndex hosted documentation for main (#143)

Co-authored-by: Moritz Lang <[email protected]>

Author: heckj

Sources/Tracing/Docs.docc/Guides/InstrumentYourLibrary.md

@@ -238,7 +238,7 @@ func handler(request: HTTPRequest) async {
 }
 ```
 
-This is introducing multiple layers of nesting, and we have un-necessarily restored, picked-up, and restored the context again. In order to avoid this duplicate work, it is beneficial to use the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` overload, which also accepts a `ServiceContext` as parameter, rather than picking it up from the task-local value:
+This is introducing multiple layers of nesting, and we have un-necessarily restored, picked-up, and restored the context again. In order to avoid this duplicate work, it is beneficial to use the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` overload, which also accepts a `ServiceContext` as parameter, rather than picking it up from the task-local value:
 
 ```swift
 // BETTER
@@ -257,7 +257,7 @@ This method will only restore the context once, after the tracer has had a chanc
 
 #### Manual Span Lifetime Management
 
-While the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` API is preferable in most situations, it may not be possible to use when the lifetime of a span only terminates in yet another callback API. In such situations, it may be impossible to "wrap" the entire piece of code that would logically represent "the span" using a `withSpan(...) { ... }` call.
+While the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` API is preferable in most situations, it may not be possible to use when the lifetime of a span only terminates in yet another callback API. In such situations, it may be impossible to "wrap" the entire piece of code that would logically represent "the span" using a `withSpan(...) { ... }` call.
 
 In such situations you can resort to using the ``startSpan(_:context:ofKind:at:function:file:line:)`` and ``Span/end()`` APIs explicitly. Those APIs can then be used like this:
 

Sources/Tracing/Docs.docc/Guides/TraceYourApplication.md

@@ -258,7 +258,7 @@ This was just a quick introduction to tracing, but hopefully you are now excited
 
 ### Efficiently working with Spans
 
-We already saw the basic API to spawn a trace span, the ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` method, but we didn't discuss it in depth yet. In this section we'll discuss how to efficiently work with spans and some common patterns and practices.
+We already saw the basic API to spawn a trace span, the ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` method, but we didn't discuss it in depth yet. In this section we'll discuss how to efficiently work with spans and some common patterns and practices.
 
 Firstly, spans are created using a `withSpan` call and performing the operation contained within the span in the trailing operation closure body. This is important because it automatically, and correctly, delimits the lifetime of the span: from its creation, until the operation closure returns:
 

Sources/Tracing/Docs.docc/Tracer.md

@@ -4,9 +4,9 @@
 
 ### Creating Spans
 
-- ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b``
+- ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v``
 
 ### Manual Span management
 
-- ``startSpan(_:context:ofKind:at:function:file:line:)-u1y4``
+- ``startSpan(_:context:ofKind:at:function:file:line:)-c9un``
 - ``Span/end()``

Sources/Tracing/SpanProtocol.swift

@@ -136,7 +136,7 @@ extension Span {
     /// Implementations SHOULD prevent double-emitting by marking a span as ended internally, however it still is a
     /// programming mistake to rely on this behavior.
     ///
-    /// - SeeAlso: ``end(clock:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it.
+    /// - SeeAlso: ``end(at:)`` which allows passing in a specific time, e.g. if the operation was ended and recorded somewhere and we need to post-factum record it.
     ///   Generally though prefer using the ``end()`` version of this API in user code and structure your system such that it can be called in the right place and time.
     public func end() {
         self.end(at: DefaultTracerClock.now)

Sources/Tracing/Tracer.swift

@@ -24,7 +24,7 @@ import Dispatch
 /// we're about to start a top-level span, or if a span should be started from a different,
 /// stored away previously,
 ///
-/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
 ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
 ///   Use `startSpan` iff you need to pass the span manually to a different
 ///   location in your source code to end it.
@@ -71,7 +71,7 @@ public func startSpan<Instant: TracerInstant>(
 /// we're about to start a top-level span, or if a span should be started from a different,
 /// stored away previously,
 ///
-/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
 ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
 ///   Use `startSpan` iff you need to pass the span manually to a different
 ///   location in your source code to end it.
@@ -116,7 +116,7 @@ public func startSpan(
 /// we're about to start a top-level span, or if a span should be started from a different,
 /// stored away previously,
 ///
-/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+/// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
 ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
 ///   Use `startSpan` iff you need to pass the span manually to a different
 ///   location in your source code to end it.

Sources/Tracing/TracerProtocol+Legacy.swift

@@ -21,7 +21,7 @@ import Dispatch
 /// **This protocol will be deprecated as soon as possible**, and the library will continue recommending Swift 5.7+
 /// in order to make use of new language features that make expressing the tracing API free of existential types when not necessary.
 ///
-/// When possible, prefer using ``Tracer`` and ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` APIs,
+/// When possible, prefer using ``Tracer`` and ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` APIs,
 /// rather than these `startAnySpan` APIs which unconditionally always return existential Spans even when not necessary
 /// (under Swift 5.7+ type-system enhancement wrt. protocols with associated types)..
 @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) // for TaskLocal ServiceContext
@@ -39,7 +39,7 @@ public protocol LegacyTracer: Instrument {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -96,7 +96,7 @@ extension LegacyTracer {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -146,7 +146,7 @@ extension LegacyTracer {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -407,7 +407,7 @@ extension Tracer {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -456,7 +456,7 @@ extension Tracer {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -511,7 +511,7 @@ extension Tracer {
     ///
     /// - Note: Legacy API, prefer using ``startSpan(_:context:ofKind:at:
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.

Sources/Tracing/TracerProtocol.swift

@@ -34,7 +34,7 @@ public protocol Tracer: LegacyTracer {
     /// we're about to start a top-level span, or if a span should be started from a different,
     /// stored away previously,
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.
@@ -71,7 +71,7 @@ extension Tracer {
     /// we're about to start a top-level span, or if a span should be started from a different,
     /// stored away previously,
     ///
-    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-4o2b`` to start
+    /// - Note: Prefer ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v`` to start
     ///   a span as it automatically takes care of ending the span, and recording errors when thrown.
     ///   Use `startSpan` iff you need to pass the span manually to a different
     ///   location in your source code to end it.