fix: doc cleanup after refactor and reorg (#87)

ordo-one · Mar 6, 2023 · 7d6f5f9 · 7d6f5f9
1 parent 400c480
commit 7d6f5f9
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 2 deletions.
diff --git a/Sources/Benchmark/BenchmarkResult.swift b/Sources/Benchmark/BenchmarkResult.swift
@@ -52,12 +52,23 @@ public enum BenchmarkTimeUnits: Int, Codable, CustomStringConvertible {
     }
 }
 
+/// The scaling factor for benchmark iterations.
+///
+/// Typically used for very fast-running benchmarks.
+/// In those cases, the time to measure the benchmark can impact as much as the time to run the code being benchmarked.
+/// Use a scaling factor when running your short benchmarks to provide greater numerical stability to the results.
 public enum BenchmarkScalingFactor: Int, Codable {
+    /// No scaling factor, the raw count of iterations.
     case one = 1 // e.g. nanoseconds, or count
+    /// Scaling factor of 1e03.
     case kilo = 1_000 // microseconds
+    /// Scaling factor of 1e06.
     case mega = 1_000_000 // milliseconds
+    /// Scaling factor of 1e09.
     case giga = 1_000_000_000 // seconds
+    /// Scaling factor of 1e12.
     case tera = 1_000_000_000_000 // 1K seconds
+    /// Scaling factor of 1e15.
     case peta = 1_000_000_000_000_000 // 1M
 
     public var description: String {

diff --git a/Sources/Benchmark/Documentation.docc/BenchmarkScalingFactor.md b/Sources/Benchmark/Documentation.docc/BenchmarkScalingFactor.md
@@ -0,0 +1,19 @@
+# ``Benchmark/BenchmarkScalingFactor``
+
+## Topics
+
+### Selecting Scaling Factors
+
+- ``Benchmark/BenchmarkScalingFactor/one``
+- ``Benchmark/BenchmarkScalingFactor/kilo``
+- ``Benchmark/BenchmarkScalingFactor/mega``
+- ``Benchmark/BenchmarkScalingFactor/giga``
+- ``Benchmark/BenchmarkScalingFactor/tera``
+- ``Benchmark/BenchmarkScalingFactor/peta``
+- ``Benchmark/BenchmarkScalingFactor/init(_:)``
+- ``Benchmark/BenchmarkScalingFactor/init(rawValue:)``
+
+### Describing the Scaling Factor
+
+- ``Benchmark/BenchmarkScalingFactor/description``
+
diff --git a/Sources/Benchmark/Documentation.docc/Documentation.md b/Sources/Benchmark/Documentation.docc/Documentation.md
@@ -28,7 +28,6 @@ That being said, some of the export formats do include more traditional average/
 
 - <doc:GettingStarted>
 - <doc:WritingBenchmarks>
-- <doc:ConfiguringBenchmarks>
 - <doc:Metrics>
 - <doc:RunningBenchmarks>
 - <doc:Workflows>
@@ -39,9 +38,10 @@ That being said, some of the export formats do include more traditional average/
 
 ### Configuring Benchmarks
 
-- ``Benchmark/Benchmark/Configuration-swift.struct`` 
+- ``Benchmark/Benchmark/Configuration-swift.struct``
 - ``Benchmark/BenchmarkMetric``
 - ``Benchmark/BenchmarkTimeUnits``
+- ``Benchmark/BenchmarkScalingFactor``
 
 ### Registering Benchmarks