Organizing documentation, cleanup and polish (#185)

Co-authored-by: Konrad `ktoso` Malawski <[email protected]>
Co-authored-by: Konrad `ktoso` Malawski <[email protected]>

Author: heckj

Sources/InMemoryTracing/Documentation.docc/Documentation.md

@@ -0,0 +1,12 @@
+# ``InMemoryTracing``
+
+In-memory implementations of tracers to provide test-focused or other programmatic access to spans.
+
+## Topics
+
+### In-memory implementations
+
+- ``InMemoryTracer``
+- ``InMemorySpan``
+- ``InMemorySpanContext``
+- ``FinishedInMemorySpan``

Sources/InMemoryTracing/InMemorySpan.swift

@@ -15,11 +15,14 @@
 @_spi(Locking) import Instrumentation
 import Tracing
 
-/// A ``Span`` created by the ``InMemoryTracer`` that will be retained in memory when ended.
-/// See ``InMemoryTracer/
+/// A span created by the in-memory tracer that is retained in memory when the trace ends.
+///
+/// An `InMemorySpan` is created by a ``InMemoryTracer``.
 public struct InMemorySpan: Span {
 
+    /// The service context of the span.
     public let context: ServiceContext
+    /// The in-memory span context.
     public var spanContext: InMemorySpanContext {
         context.inMemorySpanContext!
     }
@@ -33,12 +36,15 @@ public struct InMemorySpan: Span {
         spanContext.spanID
     }
     /// The ID of the parent span of this span, if there was any.
-    /// When this is `nil` it means this is the top-level span of this trace.
+    ///
+    /// When `nil`, this is the top-level span of this trace.
     public var parentSpanID: String? {
         spanContext.parentSpanID
     }
 
+    /// The kind of span
     public let kind: SpanKind
+    /// The time instant the span started.
     public let startInstant: any TracerInstant
 
     private let _operationName: LockedValueBox<String>
@@ -50,6 +56,14 @@ public struct InMemorySpan: Span {
     private let _isRecording = LockedValueBox<Bool>(true)
     private let onEnd: @Sendable (FinishedInMemorySpan) -> Void
 
+    /// Creates a new in-memory span
+    /// - Parameters:
+    ///   - operationName: The operation name this span represents.
+    ///   - context: The service context for the span.
+    ///   - spanContext: The in-memory span context.
+    ///   - kind: The kind of span.
+    ///   - startInstant: The time instant the span started.
+    ///   - onEnd: A closure invoked when the span completes, providing access to the finished span.
     public init(
         operationName: String,
         context: ServiceContext,
@@ -67,12 +81,15 @@ public struct InMemorySpan: Span {
         self.onEnd = onEnd
     }
 
-    /// The in memory span stops recording (storing mutations performed on the span) when it is ended.
-    /// In other words, a finished span no longer is mutable and will ignore all subsequent attempts to mutate.
+    /// A Boolean value that indicates whether the span is still recording mutations.
+    ///
+    /// The in memory span stops recording mutations performed on the span when it is ended.
+    /// In other words, a finished span is not mutable and ignores all subsequent attempts to mutate.
     public var isRecording: Bool {
         _isRecording.withValue { $0 }
     }
 
+    /// The operation name the span represents.
     public var operationName: String {
         get {
             _operationName.withValue { $0 }
@@ -83,6 +100,7 @@ public struct InMemorySpan: Span {
         }
     }
 
+    /// The span attributes.
     public var attributes: SpanAttributes {
         get {
             _attributes.withValue { $0 }
@@ -93,28 +111,40 @@ public struct InMemorySpan: Span {
         }
     }
 
+    /// The events associated with the span.
     public var events: [SpanEvent] {
         _events.withValue { $0 }
     }
 
+    /// Adds an event you provide to the span.
+    /// - Parameter event: The event to record.
     public func addEvent(_ event: SpanEvent) {
         guard isRecording else { return }
         _events.withValue { $0.append(event) }
     }
 
+    /// The span links.
     public var links: [SpanLink] {
         _links.withValue { $0 }
     }
 
+    /// Adds a link to the span.
+    /// - Parameter link: The link to add.
     public func addLink(_ link: SpanLink) {
         guard isRecording else { return }
         _links.withValue { $0.append(link) }
     }
 
+    /// The errors recorded by the span.
     public var errors: [RecordedError] {
         _errors.withValue { $0 }
     }
 
+    /// Records an error to the span.
+    /// - Parameters:
+    ///   - error: The error to record.
+    ///   - attributes: Span attributes associated with the error.
+    ///   - instant: The time instant of the error.
     public func recordError(
         _ error: any Error,
         attributes: SpanAttributes,
@@ -126,15 +156,20 @@ public struct InMemorySpan: Span {
         }
     }
 
+    /// The status of the span.
     public var status: SpanStatus? {
         _status.withValue { $0 }
     }
 
+    /// Updates the status of the span to the value you provide.
+    /// - Parameter status: The status to set.
     public func setStatus(_ status: SpanStatus) {
         guard isRecording else { return }
         _status.withValue { $0 = status }
     }
 
+    /// Finishes the span.
+    /// - Parameter instant: the time instant the span completed.
     public func end(at instant: @autoclosure () -> some TracerInstant) {
         let shouldRecord = _isRecording.withValue {
             let value = $0
@@ -158,19 +193,25 @@ public struct InMemorySpan: Span {
         onEnd(finishedSpan)
     }
 
+    /// An error recorded to a span.
     public struct RecordedError: Sendable {
+        /// The recorded error.
         public let error: Error
+        /// The span attributes associated with the error.
         public let attributes: SpanAttributes
+        /// The time instant the error occured.
         public let instant: any TracerInstant
     }
 }
 
-/// Represents a finished span (a ``Span`` that `end()` was called on)
-/// that was recorded by the ``InMemoryTracer``.
+/// A type that represents a completed span recorded by the in-memory tracer.
 public struct FinishedInMemorySpan: Sendable {
+    /// The name of the operation the span represents.
     public var operationName: String
 
+    /// The service context of the finished span.
     public var context: ServiceContext
+    /// The in-memory span context.
     public var spanContext: InMemorySpanContext {
         get {
             context.inMemorySpanContext!
@@ -189,7 +230,7 @@ public struct FinishedInMemorySpan: Sendable {
             spanContext.spanID = newValue
         }
     }
-    /// The ID of this concrete span.
+    /// The ID of this span.
     public var spanID: String {
         get {
             spanContext.spanID
@@ -199,7 +240,8 @@ public struct FinishedInMemorySpan: Sendable {
         }
     }
     /// The ID of the parent span of this span, if there was any.
-    /// When this is `nil` it means this is the top-level span of this trace.
+    ///
+    /// When `nil`, this is the top-level span of this trace.
     public var parentSpanID: String? {
         get {
             spanContext.parentSpanID
@@ -209,12 +251,20 @@ public struct FinishedInMemorySpan: Sendable {
         }
     }
 
+    /// The kind of span.
     public var kind: SpanKind
+    /// The time instant the span started.
     public var startInstant: any TracerInstant
+    /// The time instant the span ended.
     public var endInstant: any TracerInstant
+    /// The span attributes.
     public var attributes: SpanAttributes
+    /// A list of events recorded to the span.
     public var events: [SpanEvent]
+    /// A list of links added to the span.
     public var links: [SpanLink]
+    /// A list of errors recorded to the span.
     public var errors: [InMemorySpan.RecordedError]
+    /// The span status.
     public var status: SpanStatus?
 }

Sources/InMemoryTracing/InMemorySpanContext.swift

@@ -14,18 +14,24 @@
 
 import ServiceContextModule
 
-/// Encapsulates the `traceID`, `spanID` and `parentSpanID` of an `InMemorySpan`.
+/// A type that encapsulates the trace ID, span ID, and parent span ID of an in-memory span.
+///
 /// Generally used through the `ServiceContext/inMemorySpanContext` task local value.
 public struct InMemorySpanContext: Sendable, Hashable {
-    /// Idenfifier of top-level trace of which this span is a part of.
+    /// The idenfifier of top-level trace of which this span is a part of.
     public var traceID: String
 
-    /// Identifier of this specific span.
+    /// The identifier of this span.
     public var spanID: String
 
-    // Identifier of the parent of this span, if any.
+    /// The Identifier of the parent of this span, if any.
     public var parentSpanID: String?
 
+    /// Creates a new in-memory span context.
+    /// - Parameters:
+    ///   - traceID: The trace ID for the context.
+    ///   - spanID: The span ID for the context.
+    ///   - parentSpanID: The context's parent span ID.
     public init(traceID: String, spanID: String, parentSpanID: String?) {
         self.traceID = traceID
         self.spanID = spanID
@@ -34,7 +40,7 @@ public struct InMemorySpanContext: Sendable, Hashable {
 }
 
 extension ServiceContext {
-    /// Task-local value representing the current tracing ``Span`` as set by the ``InMemoryTracer``.
+    /// A task-local value that represents the current tracing span as set by the in-memory tracer.
     public var inMemorySpanContext: InMemorySpanContext? {
         get {
             self[InMemorySpanContextKey.self]