Merge branch 'apple-main'

Author: Anthony-Eid

Dockerfile

@@ -1,12 +1,12 @@
 # This source file is part of the Swift.org open source project
 #
-# Copyright (c) 2021 Apple Inc. and the Swift project authors
+# Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
 # Licensed under Apache License v2.0 with Runtime Library Exception
 #
 # See https://swift.org/LICENSE.txt for license information
 # See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
-FROM swift:5.5
+FROM swift:5.9-focal
 
 # Set up the current build user in the same way done in the Swift.org CI system: 
 # https://github.com/apple/swift-docker/blob/main/swift-ci/master/ubuntu/20.04/Dockerfile.

Package.resolved

@@ -60,7 +60,7 @@
       "location" : "https://github.com/apple/swift-docc-symbolkit",
       "state" : {
         "branch" : "main",
-        "revision" : "3889b9673fcf1f1e9651b9143289b6ede462c958"
+        "revision" : "a6ac00f3534293eeec73c37a396a1bac27816094"
       }
     },
     {
@@ -78,7 +78,7 @@
       "location" : "https://github.com/apple/swift-markdown.git",
       "state" : {
         "branch" : "main",
-        "revision" : "e5ab90941a8415304b4a4e403253bd59fef00b5a"
+        "revision" : "75bd31951f69b9df43d433b75152d8add1692378"
       }
     },
     {

Package.swift

@@ -1,8 +1,8 @@
-// swift-tools-version:5.6
+// swift-tools-version:5.9
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -90,6 +90,7 @@ let package = Package(
         .target(
             name: "SwiftDocCTestUtilities",
             dependencies: [
+                .target(name: "SwiftDocC"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
             swiftSettings: swiftSettings

Sources/SwiftDocC/Benchmark/Benchmark.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -94,38 +94,48 @@ private extension Benchmark {
 }
 
 /// Logs a one-off metric value.
-/// - Parameter event: The metric to add to the log.
-public func benchmark<E>(add event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) where E: BenchmarkMetric {
+/// - Parameters:
+///   - metric: The one-off metric
+///   - log: The log to add the metric to.
+public func benchmark<E>(add metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) where E: BenchmarkMetric {
     guard log.shouldLogMetricType(E.self) else { return }
 
-    log.metrics.append(event())
+    log.metrics.append(metric())
 }
 
-/// Starts the given metric.
-/// - Parameter event: The metric to start.
-public func benchmark<E>(begin event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) -> E? where E: BenchmarkBlockMetric {
+/// Begins the given metric.
+/// - Parameters:
+///   - metric: The metric to begin measuring.
+///   - log: The log that may filter out the metric.
+public func benchmark<E>(begin metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main) -> E? where E: BenchmarkBlockMetric {
     guard log.shouldLogMetricType(E.self) else { return nil }
 
-    let event = event()
-    event.begin()
-    return event
+    let metric = metric()
+    metric.begin()
+    return metric
 }
 
 /// Ends the given metric and adds it to the log.
-/// - Parameter event: The metric to end and log.
-public func benchmark<E>(end event: @autoclosure () -> E?, benchmarkLog log: Benchmark = .main) where E: BenchmarkBlockMetric {
-    guard log.shouldLogMetricType(E.self), let event = event() else { return }
+/// - Parameters:
+///   - metric: The metric to end and log.
+///   - log: The log to add the metric to.
+public func benchmark<E>(end metric: @autoclosure () -> E?, benchmarkLog log: Benchmark = .main) where E: BenchmarkBlockMetric {
+    guard log.shouldLogMetricType(E.self), let metric = metric() else { return }
 
-    event.end()
-    log.metrics.append(event)
+    metric.end()
+    log.metrics.append(metric)
 }
 
-/// Ends the given metric and adds it to the log.
-/// - Parameter event: The metric to end and log.
 @discardableResult
-public func benchmark<E, Result>(wrap event: @autoclosure () -> E, benchmarkLog log: Benchmark = .main, body: () throws -> Result) rethrows -> Result where E: BenchmarkBlockMetric {
+/// Measures a metric around the given closure.
+/// - Parameters:
+///   - metric: The metric to measure and log.
+///   - log: The log to add the metric to.
+///   - body: The closure around which to measure the metric.
+/// - Returns: The return value from the closure.
+public func benchmark<E, Result>(wrap metric: @autoclosure () -> E, benchmarkLog log: Benchmark = .main, body: () throws -> Result) rethrows -> Result where E: BenchmarkBlockMetric {
     if log.shouldLogMetricType(E.self) {
-        let event = event()
+        let event = metric()
         event.begin()
         let result = try body()
         event.end()

Sources/SwiftDocC/Benchmark/Metrics/ExternalTopicsHash.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -11,19 +11,18 @@
 import Foundation
 
 extension Benchmark {
-    /// A hash metric produced off the externally resolved links and symbols.
+    /// A hash metric produced off the externally resolved links.
     ///
-    /// Use this metric to verify that your code changes
-    /// did not affect external resolving.
+    /// Use this metric to verify that your code changes did not affect external link resolution.
     public class ExternalTopicsHash: BenchmarkMetric {
         public static let identifier = "external-topics-hash"
         public static let displayName = "External Topics Checksum"
 
-        /// Creates a new metric and stores the checksum of the given documentation context external topics.
-        /// - Parameter context: A documentation context.
+        /// Creates a new metric that stores the checksum of the successfully externally resolved links.
+        /// - Parameter context: A documentation context that the external links were resolved in.
         public init(context: DocumentationContext) {
             // If there are no externally resolved topics return quickly.
-            guard !context.externallyResolvedLinks.isEmpty || !context.externallyResolvedSymbols.isEmpty else {
+            guard !context.externallyResolvedLinks.isEmpty else {
                 return
             }
 
@@ -37,7 +36,6 @@ extension Benchmark {
                     return nil
                 }
             }).sorted().joined()
-                + context.externallyResolvedSymbols.map({ $0.absoluteString }).sorted().joined()
 
             result = .checksum(Checksum.md5(of: Data(sourceString.utf8)))
         }