expands curation for types within the Tracing module

heckj · heckj · commit 4f7035bd8824 · 2025-09-25T12:53:04.000-07:00
diff --git a/Sources/Tracing/Docs.docc/LegacyTracer.md b/Sources/Tracing/Docs.docc/LegacyTracer.md
diff --git a/Sources/Tracing/Docs.docc/Reference/DefaultTracerClock-Timestamp.md b/Sources/Tracing/Docs.docc/Reference/DefaultTracerClock-Timestamp.md
@@ -0,0 +1,18 @@
+# ``Tracing/DefaultTracerClock/Timestamp``
+
+## Topics
+
+### Creating timestamps
+
+- ``init()``
+- ``init(nanosecondsSinceEpoch:)``
+
+### Inspecting timestamps
+
+- ``nanosecondsSinceEpoch``
+
+### Comparing timestamps
+
+- ``==(_:_:)``
+- ``<(_:_:)``
+- ``hash(into:)``
diff --git a/Sources/Tracing/Docs.docc/Reference/DefaultTracerClock.md b/Sources/Tracing/Docs.docc/Reference/DefaultTracerClock.md
@@ -0,0 +1,14 @@
+# ``Tracing/DefaultTracerClock``
+
+## Topics
+
+### Creating a default tracer clock
+
+- ``init()``
+
+### Inspecting the clock
+
+- ``now-type.property``
+- ``now-property``
+- ``Instant``
+- ``Timestamp``
diff --git a/Sources/Tracing/Docs.docc/Reference/InstrumentationSystem.md b/Sources/Tracing/Docs.docc/Reference/InstrumentationSystem.md
@@ -0,0 +1,6 @@
+# ``Tracing/Instrumentation/InstrumentationSystem``
+
+## Topics
+
+- ``tracer``
+- ``legacyTracer``
diff --git a/Sources/Tracing/Docs.docc/Reference/LegacyTracer.md b/Sources/Tracing/Docs.docc/Reference/LegacyTracer.md
@@ -0,0 +1,20 @@
+# ``Tracing/LegacyTracer``
+
+## Topics
+
+### Creating Spans
+
+- ``withAnySpan(_:context:ofKind:function:file:line:_:)-9jni8``
+- ``withAnySpan(_:at:context:ofKind:function:file:line:_:)-7fz6i``
+- ``withAnySpan(_:context:ofKind:isolation:function:file:line:_:)``
+- ``withAnySpan(_:at:context:ofKind:isolation:function:file:line:_:)``
+
+- ``withAnySpan(_:context:ofKind:function:file:line:_:)-369ou``
+- ``withAnySpan(_:at:context:ofKind:function:file:line:_:)-6jzit``
+
+### Manually Managing Spans
+
+- ``startAnySpan(_:context:ofKind:function:file:line:)``
+- ``startAnySpan(_:at:context:ofKind:function:file:line:)``
+- ``startAnySpan(_:context:ofKind:at:function:file:line:)``
+- ``forceFlush()``
diff --git a/Sources/Tracing/Docs.docc/Reference/NestedSpanAttributesProtocol.md b/Sources/Tracing/Docs.docc/Reference/NestedSpanAttributesProtocol.md
@@ -0,0 +1,8 @@
+# ``Tracing/NestedSpanAttributesProtocol``
+
+## Topics
+
+### Created a nested set of attributes
+
+- ``init()``
+- ``Key``
diff --git a/Sources/Tracing/Docs.docc/Reference/NoOpTracer.md b/Sources/Tracing/Docs.docc/Reference/NoOpTracer.md
@@ -0,0 +1,15 @@
+# ``Tracing/NoOpTracer``
+
+## Topics
+
+### Creating a no-op tracer
+
+- ``init()``
+- ``startAnySpan(_:context:ofKind:at:function:file:line:)``
+- ``Span``
+
+### Tracer Methods
+
+- ``extract(_:into:using:)``
+- ``inject(_:into:using:)``
+- ``forceFlush()``
diff --git a/Sources/Tracing/Docs.docc/Reference/Span.md b/Sources/Tracing/Docs.docc/Reference/Span.md
@@ -0,0 +1,37 @@
+# ``Tracing/Span``
+
+## Topics
+
+### Inspecting Spans
+
+- ``operationName``
+- ``context``
+- ``isRecording``
+- ``attributes``
+
+### Updating Spans
+
+- ``setStatus(_:)``
+- ``updateAttributes(_:)``
+
+### Recording Events
+
+- ``addEvent(_:)``
+
+### Recording Errors
+
+- ``recordError(_:)``
+- ``recordError(_:attributes:)``
+- ``recordError(_:attributes:at:)``
+
+### Recording Links
+
+- ``addLink(_:)``
+- ``addLink(_:attributes:)``
+
+### Ending Spans
+
+- ``end()``
+- ``end(at:)``
+
+
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanAttribute.md b/Sources/Tracing/Docs.docc/Reference/SpanAttribute.md
@@ -0,0 +1,23 @@
+# ``Tracing/SpanAttribute``
+
+## Topics
+
+### Types of attributes
+
+- ``string(_:)``
+- ``stringArray(_:)``
+- ``stringConvertible(_:)``
+- ``stringConvertibleArray(_:)``
+- ``bool(_:)``
+- ``boolArray(_:)``
+- ``int(_:)``
+- ``int32(_:)``
+- ``int32Array(_:)``
+- ``int64(_:)``
+- ``int64Array(_:)``
+- ``double(_:)``
+- ``doubleArray(_:)``
+
+### Comparing span attributes
+
+- ``==(_:_:)``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanAttributeConvertible.md b/Sources/Tracing/Docs.docc/Reference/SpanAttributeConvertible.md
@@ -0,0 +1,7 @@
+# ``Tracing/SpanAttributeConvertible``
+
+## Topics
+
+### Converting to a span attribute
+
+- ``toSpanAttribute()``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanAttributeKey.md b/Sources/Tracing/Docs.docc/Reference/SpanAttributeKey.md
@@ -0,0 +1,12 @@
+# ``Tracing/SpanAttributeKey``
+
+## Topics
+
+### Creating span attribute keys
+
+- ``init(name:)``
+- ``init(stringLiteral:)``
+
+### Inspecting span attribute keys
+
+- ``name``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanAttributeNamespace.md b/Sources/Tracing/Docs.docc/Reference/SpanAttributeNamespace.md
@@ -0,0 +1,12 @@
+# ``Tracing/SpanAttributeNamespace``
+
+## Topics
+
+### Inspecting nested attributes
+
+- ``NestedSpanAttributes``
+- ``attributes``
+- ``subscript(dynamicMember:)-2lvpt``
+- ``subscript(dynamicMember:)-2pclq``
+- ``subscript(dynamicMember:)-b3cs``
+- ``subscript(dynamicMember:)-7xk26``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanAttributes.md b/Sources/Tracing/Docs.docc/Reference/SpanAttributes.md
@@ -0,0 +1,29 @@
+# ``Tracing/SpanAttributes``
+
+## Topics
+
+### Creating span attributes
+
+- ``init(_:)``
+
+### Accessing span attributes
+
+- ``get(_:)``
+- ``subscript(dynamicMember:)->SpanAttribute?``
+- ``subscript(_:)``
+- ``subscript(dynamicMember:)->Namespace``
+
+### Updating span attributes
+
+- ``set(_:value:)``
+- ``merge(_:)``
+
+### Inspecting span attributes
+
+- ``count``
+- ``isEmpty``
+
+### Iterating span attributes
+
+- ``forEach(_:)``
+
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanEvent.md b/Sources/Tracing/Docs.docc/Reference/SpanEvent.md
@@ -0,0 +1,16 @@
+# ``Tracing/SpanEvent``
+
+## Topics
+
+### Creating span events
+
+- ``init(stringLiteral:)``
+- ``init(name:attributes:)``
+- ``init(name:at:attributes:)``
+
+### Inspecting span events
+
+- ``name``
+- ``attributes``
+- ``millisecondsSinceEpoch``
+- ``nanosecondsSinceEpoch``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanKind.md b/Sources/Tracing/Docs.docc/Reference/SpanKind.md
@@ -0,0 +1,11 @@
+# ``Tracing/SpanKind``
+
+## Topics
+
+### Kind of spans
+
+- ``server``
+- ``internal``
+- ``client``
+- ``consumer``
+- ``producer``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanLink.md b/Sources/Tracing/Docs.docc/Reference/SpanLink.md
@@ -0,0 +1,12 @@
+# ``Tracing/SpanLink``
+
+## Topics
+
+### Creating span links
+
+- ``init(context:attributes:)``
+
+### Inspecting span links
+
+- ``context``
+- ``attributes``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanStatus-Code.md b/Sources/Tracing/Docs.docc/Reference/SpanStatus-Code.md
@@ -0,0 +1,8 @@
+# ``Tracing/SpanStatus/Code``
+
+## Topics
+
+### Span Status Codes
+
+- ``ok``
+- ``error``
diff --git a/Sources/Tracing/Docs.docc/Reference/SpanStatus.md b/Sources/Tracing/Docs.docc/Reference/SpanStatus.md
@@ -0,0 +1,13 @@
+# ``Tracing/SpanStatus``
+
+## Topics
+
+### Creating span status
+
+- ``init(code:message:)``
+
+### Inspecting span status
+
+- ``code``
+- ``message``
+- ``Code``
diff --git a/Sources/Tracing/Docs.docc/Reference/Tracer.md b/Sources/Tracing/Docs.docc/Reference/Tracer.md
@@ -0,0 +1,31 @@
+# ``Tracing/Tracer``
+
+## Topics
+
+### Creating Spans
+
+- ``withSpan(_:context:ofKind:function:file:line:_:)-9r5mu``
+- ``withSpan(_:context:ofKind:isolation:function:file:line:_:)``
+- ``withSpan(_:context:ofKind:at:function:file:line:_:)-7hfa8``
+- ``withSpan(_:context:ofKind:at:isolation:function:file:line:_:)``
+
+- ``withAnySpan(_:at:context:ofKind:function:file:line:_:)-3tj0e``
+- ``withAnySpan(_:at:context:ofKind:isolation:function:file:line:_:)``
+
+- ``Span``
+
+- ``withSpan(_:context:ofKind:function:file:line:_:)-49gj4``
+- ``withSpan(_:context:ofKind:at:function:file:line:_:)-7o9y1``
+- ``withSpan(_:context:ofKind:at:function:file:line:_:)-8gw3v``
+- ``withAnySpan(_:at:context:ofKind:function:file:line:_:)-1aiz``
+
+### Manual Span management
+
+- ``startSpan(_:context:ofKind:at:function:file:line:)-c9un``
+- ``startSpan(_:context:ofKind:at:function:file:line:)``
+- ``Span/end()``
+
+### Accessing Spans
+
+- ``activeSpan(identifiedBy:)-4ttod``
+- ``activeSpan(identifiedBy:)-4mers``
diff --git a/Sources/Tracing/Docs.docc/Reference/TracerInstant.md b/Sources/Tracing/Docs.docc/Reference/TracerInstant.md
@@ -0,0 +1,8 @@
+# ``Tracing/TracerInstant``
+
+## Topics
+
+### Converting to UNIX time values
+
+- ``millisecondsSinceEpoch``
+- ``nanosecondsSinceEpoch``
diff --git a/Sources/Tracing/Docs.docc/Tracer.md b/Sources/Tracing/Docs.docc/Tracer.md
diff --git a/Sources/Tracing/Docs.docc/index.md b/Sources/Tracing/Docs.docc/index.md
@@ -29,7 +29,8 @@ as the subsequent guides dive deeper into patterns and details of instrumenting
 
 ### Boostrapping Tracing
 
-- ``Instrumentation``
+- ``Tracing/Instrumentation/InstrumentationSystem``
+- ``Tracing/Tracer``
 - ``TracerInstant``
 - ``LegacyTracer``
 
diff --git a/Sources/Tracing/TracingTime.swift b/Sources/Tracing/TracingTime.swift
@@ -33,6 +33,7 @@ import WASILibc
 import _CWASI
 #endif
 
+/// A type that represents a point in time down to the nanosecond.
 public protocol TracerInstant: Comparable, Hashable, Sendable {
     /// Representation of this instant as the number of nanoseconds since UNIX Epoch (January 1st 1970)
     var nanosecondsSinceEpoch: UInt64 { get }
