feat(minor): Add convenience blackHole() to Benchmark, fix up documen…

…tation links (#124)

Adding convenience blackHole() to Benchmark for easier disambiguation.
Documentation links were broken after restructuring, fixing them.
Fixes #124

Sources/BenchmarkSupport/Benchmark.swift

@@ -110,7 +110,6 @@ public final class Benchmark: Codable, Hashable {
                                                                   thresholds: nil)
 
     internal static var testSkipBenchmarkRegistrations = false // true in test to avoid bench registration fail
-
     var measurementCompleted = false // Keep track so we skip multiple 'end of measurement'
 
     enum CodingKeys: String, CodingKey {
@@ -373,3 +372,29 @@ public extension Benchmark {
         }
     }
 }
+
+// This is an additional convenience duplicating the free standing function blackHole() for those cases where
+// another module happens to define it, as we have a type clash between module name and type name and otherwise
+// the user would need to do `import func Benchmark.blackHole` which isn't that obvious - thus this duplication.
+public extension Benchmark {
+    /// A function to foil compiler optimizations that would otherwise optimize out code you want to benchmark.
+    ///
+    /// The function wraps another object or function, does nothing, and returns.
+    /// If you want to benchmark the time is takes to create an instance and you don't maintain a reference to it, the compiler may optimize it out entirely, thinking it is unused.
+    /// To prevent the compiler from removing the code you want to measure, wrap the creation of the instance with `blackHole`.
+    /// For example, the following code benchmarks the time it takes to create an instance of `Date`, and wraps the creation of the instance to prevent the compiler from optimizing it away:
+    ///
+    /// ```swift
+    /// Benchmark("Foundation Date()",
+    ///     configuration: .init(
+    ///         metrics: [.throughput, .wallClock],
+    ///         scalingFactor: .mega)
+    /// ) { benchmark in
+    ///     for _ in benchmark.scaledIterations {
+    ///         Benchmark.blackHole(Date())
+    ///     }
+    /// }
+    /// ```
+    @inline(never)
+    static func blackHole(_: some Any) {}
+}

Sources/BenchmarkSupport/Documentation.docc/Benchmark.md

@@ -0,0 +1,46 @@
+# ``BenchmarkSupport/Benchmark``
+
+## Topics
+
+### AllSymbols
+
+### Creating Benchmarks
+
+- ``Benchmark/init(_:configuration:closure:)-3tbq``
+- ``Benchmark/init(_:configuration:closure:)-4rphh``
+- ``Benchmark/init(_:configuration:closure:)-3fdz8``
+- ``Benchmark/init(_:configuration:closure:)-1s1pj``
+
+### Configuring Benchmarks
+
+- ``Benchmark/configuration-swift.property``
+- ``Benchmark/defaultConfiguration``
+- ``Benchmark/Configuration-swift.struct``
+- ``Benchmark/checkAbsoluteThresholds``
+
+### Writing Benchmarks
+
+- ``Benchmark/scaledIterations``
+- ``Benchmark/startMeasurement()``
+- ``Benchmark/stopMeasurement()``
+
+### Inspecting Benchmarks
+
+- ``Benchmark/name``
+- ``Benchmark/currentIteration``
+- ``Benchmark/error(_:)``
+- ``Benchmark/failureReason``
+
+### Collecting Custom Metrics
+
+- ``Benchmark/measurement(_:_:)``
+- ``Benchmark/customMetricMeasurement``
+
+### Decoding Benchmarks
+
+- ``Benchmark/init(from:)``
+
+### Comparing Benchmarks
+
+- ``Benchmark/!=(_:_:)``
+

Sources/BenchmarkSupport/Documentation.docc/BenchmarkMetric.md

@@ -0,0 +1,66 @@
+# ``BenchmarkSupport/BenchmarkMetric``
+
+## Topics
+
+### Metric Collections
+
+- ``BenchmarkMetric/default``
+- ``BenchmarkMetric/system``
+- ``BenchmarkMetric/extended``
+- ``BenchmarkMetric/memory``
+- ``BenchmarkMetric/disk``
+- ``BenchmarkMetric/all``
+
+### System Metrics
+
+- ``BenchmarkMetric/wallClock``
+- ``BenchmarkMetric/syscalls``
+- ``BenchmarkMetric/contextSwitches``
+- ``BenchmarkMetric/threads``
+- ``BenchmarkMetric/threadsRunning``
+- ``BenchmarkMetric/cpuSystem``
+- ``BenchmarkMetric/cpuUser``
+
+### Extended System Metrics
+
+- ``BenchmarkMetric/wallClock``
+- ``BenchmarkMetric/cpuTotal``
+- ``BenchmarkMetric/mallocCountTotal``
+- ``BenchmarkMetric/throughput``
+- ``BenchmarkMetric/peakMemoryResident``
+- ``BenchmarkMetric/memoryLeaked``
+- ``BenchmarkMetric/allocatedResidentMemory``
+
+### Memory Metrics
+
+- ``BenchmarkMetric/peakMemoryResident``
+- ``BenchmarkMetric/peakMemoryVirtual``
+- ``BenchmarkMetric/mallocCountSmall``
+- ``BenchmarkMetric/mallocCountLarge``
+- ``BenchmarkMetric/mallocCountTotal``
+- ``BenchmarkMetric/memoryLeaked``
+- ``BenchmarkMetric/allocatedResidentMemory``
+
+### Disk Metrics
+
+- ``BenchmarkMetric/readSyscalls``
+- ``BenchmarkMetric/writeSyscalls``
+- ``BenchmarkMetric/readBytesLogical``
+- ``BenchmarkMetric/writeBytesLogical``
+- ``BenchmarkMetric/readBytesPhysical``
+- ``BenchmarkMetric/writeBytesPhysical``
+
+### Custom Metrics
+
+- ``BenchmarkMetric/custom(_:polarity:useScalingFactor:)``
+- ``BenchmarkMetric/polarity-swift.property``
+- ``BenchmarkMetric/Polarity-swift.enum``
+
+### Inspecting Metrics
+
+- ``BenchmarkMetric/description``
+- ``BenchmarkMetric/countable``
+
+### Decoding a Metric
+
+- ``BenchmarkMetric/init(from:)``

Sources/BenchmarkSupport/Documentation.docc/BenchmarkMetric_Polarity.md

@@ -0,0 +1,12 @@
+# ``BenchmarkSupport/BenchmarkMetric/Polarity``
+
+## Topics
+
+### Types of Polarity
+
+- ``BenchmarkMetric/Polarity/prefersLarger``
+- ``BenchmarkMetric/Polarity/prefersSmaller``
+
+### Decoding Polarity
+
+- ``BenchmarkMetric/Polarity/init(from:)``

Sources/BenchmarkSupport/Documentation.docc/BenchmarkScalingFactor.md

@@ -0,0 +1,19 @@
+# ``BenchmarkSupport/BenchmarkScalingFactor``
+
+## Topics
+
+### Selecting Scaling Factors
+
+- ``BenchmarkScalingFactor/one``
+- ``BenchmarkScalingFactor/kilo``
+- ``BenchmarkScalingFactor/mega``
+- ``BenchmarkScalingFactor/giga``
+- ``BenchmarkScalingFactor/tera``
+- ``BenchmarkScalingFactor/peta``
+- ``BenchmarkScalingFactor/init(_:)``
+- ``BenchmarkScalingFactor/init(rawValue:)``
+
+### Describing the Scaling Factor
+
+- ``BenchmarkScalingFactor/description``
+