some more docs for the types

Author: ktoso

Sources/MetricsTestUtils/TestMetrics.swift

@@ -143,16 +143,23 @@ extension TestMetrics.FullKey: Hashable {
 
 extension TestMetrics {
     // ==== ------------------------------------------------------------------------------------------------------------
-
     // MARK: Counter
 
+    /// Assert that the passed in `metric` is a ``TestCounter`` and return it for further executing assertions.
     public func expectCounter(_ metric: Counter) throws -> TestCounter {
         guard let counter = metric._handler as? TestCounter else {
             throw TestMetricsError.illegalMetricType(metric: metric._handler, expected: "\(TestCounter.self)")
         }
         return counter
     }
 
+    /// Locate a ``TestCounter`` created by the ``TestMetrics`` factory identified by the passed in ``label`` and ``dimensions``, and return it for further executing assertions.
+    ///
+    /// - Parameters:
+    ///   - label: the expected label the looked for metric should have
+    ///   - dimensions: the expected dimensions the looked for metric should have
+    /// - Returns: the underlying ``TestMetric``
+    /// - Throws: when no such test metric was present
     public func expectCounter(_ label: String, _ dimensions: [(String, String)] = []) throws -> TestCounter {
         let maybeItem = self.lock.withLock {
             self.counters[.init(label: label, dimensions: dimensions)]
@@ -167,28 +174,41 @@ extension TestMetrics {
     }
 
     // ==== ------------------------------------------------------------------------------------------------------------
-
     // MARK: Gauge
 
+    /// Assert that the passed in `metric` is a ``TestRecorder`` and return it for further executing assertions.
     public func expectGauge(_ metric: Gauge) throws -> TestRecorder {
         return try self.expectRecorder(metric)
     }
-
+    /// Locate a ``TestRecorder`` created by the ``TestMetrics`` factory identified by the passed in ``label`` and ``dimensions``, and return it for further executing assertions.
+    ///
+    /// - Parameters:
+    ///   - label: the expected label the looked for metric should have
+    ///   - dimensions: the expected dimensions the looked for metric should have
+    /// - Returns: the underlying ``TestRecorder``
+    /// - Throws: when no such test metric was present
     public func expectGauge(_ label: String, _ dimensions: [(String, String)] = []) throws -> TestRecorder {
         return try self.expectRecorder(label, dimensions)
     }
 
     // ==== ------------------------------------------------------------------------------------------------------------
-
     // MARK: Recorder
 
+    /// Assert that the passed in `metric` is a ``TestRecorder`` and return it for further executing assertions.
     public func expectRecorder(_ metric: Recorder) throws -> TestRecorder {
         guard let recorder = metric._handler as? TestRecorder else {
             throw TestMetricsError.illegalMetricType(metric: metric._handler, expected: "\(TestRecorder.self)")
         }
         return recorder
     }
 
+    /// Locate a ``TestRecorder`` created by the ``TestMetrics`` factory identified by the passed in ``label`` and ``dimensions``, and return it for further executing assertions.
+    ///
+    /// - Parameters:
+    ///   - label: the expected label the looked for metric should have
+    ///   - dimensions: the expected dimensions the looked for metric should have
+    /// - Returns: the underlying ``TestRecorder``
+    /// - Throws: when no such test metric was present
     public func expectRecorder(_ label: String, _ dimensions: [(String, String)] = []) throws -> TestRecorder {
         let maybeItem = self.lock.withLock {
             self.recorders[.init(label: label, dimensions: dimensions)]
@@ -203,16 +223,23 @@ extension TestMetrics {
     }
 
     // ==== ------------------------------------------------------------------------------------------------------------
-
     // MARK: Timer
 
+    /// Assert that the passed in `metric` is a ``TestTimer`` and return it for further executing assertions.
     public func expectTimer(_ metric: CoreMetrics.Timer) throws -> TestTimer {
         guard let timer = metric._handler as? TestTimer else {
             throw TestMetricsError.illegalMetricType(metric: metric._handler, expected: "\(TestTimer.self)")
         }
         return timer
     }
 
+    /// Locate a ``TestTimer`` created by the ``TestMetrics`` factory identified by the passed in ``label`` and ``dimensions``, and return it for further executing assertions.
+    ///
+    /// - Parameters:
+    ///   - label: the expected label the looked for metric should have
+    ///   - dimensions: the expected dimensions the looked for metric should have
+    /// - Returns: the underlying ``TestTimer``
+    /// - Throws: when no such test metric was present
     public func expectTimer(_ label: String, _ dimensions: [(String, String)] = []) throws -> TestTimer {
         let maybeItem = self.lock.withLock {
             self.timers[.init(label: label, dimensions: dimensions)]
@@ -231,12 +258,18 @@ extension TestMetrics {
 
 // MARK: Metric type implementations
 
+/// Common protocol for all test metrics, created by the ``TestMetrics`` metrics backend.
 public protocol TestMetric {
     associatedtype Value
 
+    /// Key used to identify a metric.
     var key: TestMetrics.FullKey { get }
 
+    /// Last metric value that was recorded into this metric.
     var lastValue: Value? { get }
+
+    /// Sequence of pairs of values reported into this metric, as well as the `Date` at which the metric was emitted.
+    /// The sequence is ordered from oldest to latest, so you can e.g. assert a counter growing at an expected rate etc.
     var last: (Date, Value)? { get }
 }