Define commands/actions as asynchronous

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/DocumentationConverter.swift

@@ -50,6 +50,7 @@ public struct DocumentationConverter: DocumentationConverterProtocol {
     private var dataProvider: DocumentationWorkspaceDataProvider
 
     /// An optional closure that sets up a context before the conversion begins.
+    @available(*, deprecated, message: "This deprecated API will be removed after 6.2 is released")
     public var setupContext: ((inout DocumentationContext) -> Void)?
 
     /// Conversion batches should be big enough to keep all cores busy but small enough not to keep
@@ -189,9 +190,6 @@ public struct DocumentationConverter: DocumentationConverterProtocol {
         if let dataProvider = self.currentDataProvider {
             try workspace.unregisterProvider(dataProvider)
         }
-        
-        // Do additional context setup.
-        setupContext?(&context)
 
         /*
            Asynchronously cancel registration if necessary.

Sources/SwiftDocCUtilities/Action/Action.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
@@ -13,18 +13,16 @@ import SwiftDocC
 
 /// An independent unit of work in the command-line workflow.
 ///
-/// An `Action` represents a discrete documentation task; it takes options and inputs, 
-/// performs its work, reports any problems it encounters, and outputs it generates.
-public protocol Action {
+/// An action represents a discrete documentation task; it takes options and inputs, performs its work, reports any problems it encounters, and outputs it generates.
+package protocol AsyncAction {
     /// Performs the action and returns an ``ActionResult``.
-    mutating func perform(logHandle: LogHandle) throws -> ActionResult
+    mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult
 }
 
-/// An action for which you can optionally customize the documentation context.
-public protocol RecreatingContext: Action {
-    /// A closure that an action calls with the action's context for built documentation,
-    /// before the action performs work.
-    ///
-    /// Use this closure to set the action's context to a certain state before the action runs.
-    var setupContext: ((inout DocumentationContext) -> Void)? { get set }
+package extension AsyncAction {
+    mutating func perform(logHandle: LogHandle) async throws -> ActionResult {
+        var logHandle = logHandle
+        return try await perform(logHandle: &logHandle)
+    }
 }
+

Sources/SwiftDocCUtilities/Action/Actions/Action+MoveOutput.swift

@@ -11,7 +11,7 @@
 import Foundation
 import SwiftDocC
 
-extension Action {
+extension AsyncAction {
 
     /// Creates a new unique directory, with an optional template, inside of specified container.
     /// - Parameters:

Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift

@@ -14,7 +14,7 @@ import Foundation
 import SwiftDocC
 
 /// An action that converts a source bundle into compiled documentation.
-public struct ConvertAction: Action, RecreatingContext {
+public struct ConvertAction: AsyncAction {
     enum Error: DescribedError {
         case doesNotContainBundle(url: URL)
         case cancelPending
@@ -59,12 +59,6 @@ public struct ConvertAction: Action, RecreatingContext {
     private var fileManager: FileManagerProtocol
     private let temporaryDirectory: URL
 
-    public var setupContext: ((inout DocumentationContext) -> Void)? {
-        didSet {
-            converter.setupContext = setupContext
-        }
-    }
-    
     var converter: DocumentationConverter
 
     private var durationMetric: Benchmark.Duration?
@@ -284,7 +278,7 @@ public struct ConvertAction: Action, RecreatingContext {
 
     /// Converts each eligible file from the source documentation bundle,
     /// saves the results in the given output alongside the template files.
-    mutating public func perform(logHandle: LogHandle) throws -> ActionResult {
+    public mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         // Add the default diagnostic console writer now that we know what log handle it should write to.
         if !diagnosticEngine.hasConsumer(matching: { $0 is DiagnosticConsoleWriter }) {
             diagnosticEngine.add(
@@ -451,7 +445,7 @@ public struct ConvertAction: Action, RecreatingContext {
         benchmark(end: totalTimeMetric)
 
         if !didEncounterError {
-            let coverageResults = try coverageAction.perform(logHandle: logHandle)
+            let coverageResults = try await coverageAction.perform(logHandle: &logHandle)
             postConversionProblems.append(contentsOf: coverageResults.problems)
         }
 

Sources/SwiftDocCUtilities/Action/Actions/CoverageAction.swift

@@ -12,24 +12,24 @@ import Foundation
 import SwiftDocC
 
 /// An action that creates documentation coverage info for a documentation bundle.
-public struct CoverageAction: Action {
-    internal init(
+public struct CoverageAction: AsyncAction {
+    init(
         documentationCoverageOptions: DocumentationCoverageOptions,
         workingDirectory: URL,
-        fileManager: FileManagerProtocol) {
+        fileManager: FileManagerProtocol
+    ) {
         self.documentationCoverageOptions = documentationCoverageOptions
         self.workingDirectory = workingDirectory
         self.fileManager = fileManager
     }
 
     public let documentationCoverageOptions: DocumentationCoverageOptions
-    internal let workingDirectory: URL
+    let workingDirectory: URL
     private let fileManager: FileManagerProtocol
 
-    public mutating func perform(logHandle: LogHandle) throws -> ActionResult {
+    public mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         switch documentationCoverageOptions.level {
         case .brief, .detailed:
-            var logHandle = logHandle
             print("   --- Experimental coverage output enabled. ---", to: &logHandle)
 
             let summaryString = try CoverageDataEntry.generateSummary(

Sources/SwiftDocCUtilities/Action/Actions/EmitGeneratedCurationAction.swift

@@ -12,7 +12,7 @@ import Foundation
 import SwiftDocC
 
 /// An action that emits documentation extension files that reflect the auto-generated curation.
-struct EmitGeneratedCurationAction: Action {
+struct EmitGeneratedCurationAction: AsyncAction {
     let catalogURL: URL?
     let additionalSymbolGraphDirectory: URL?
     let outputURL: URL
@@ -41,7 +41,7 @@ struct EmitGeneratedCurationAction: Action {
         self.fileManager = fileManager
     }
 
-    mutating func perform(logHandle: LogHandle) throws -> ActionResult {
+    mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         let workspace = DocumentationWorkspace()
         let context = try DocumentationContext(dataProvider: workspace)
 

Sources/SwiftDocCUtilities/Action/Actions/IndexAction.swift

@@ -12,7 +12,7 @@ import Foundation
 import SwiftDocC
 
 /// An action that creates an index of a documentation bundle.
-public struct IndexAction: Action {
+public struct IndexAction: AsyncAction {
     let rootURL: URL
     let outputURL: URL
     let bundleIdentifier: String
@@ -22,8 +22,7 @@ public struct IndexAction: Action {
     private var dataProvider: LocalFileSystemDataProvider!
 
     /// Initializes the action with the given validated options, creates or uses the given action workspace & context.
-    public init(documentationBundleURL: URL, outputURL: URL, bundleIdentifier: String, diagnosticEngine: DiagnosticEngine = .init()) throws
-    {
+    public init(documentationBundleURL: URL, outputURL: URL, bundleIdentifier: String, diagnosticEngine: DiagnosticEngine = .init()) throws {
         // Initialize the action context.
         self.rootURL = documentationBundleURL
         self.outputURL = outputURL
@@ -35,7 +34,7 @@ public struct IndexAction: Action {
 
     /// Converts each eligible file from the source documentation bundle,
     /// saves the results in the given output alongside the template files.
-    mutating public func perform(logHandle: LogHandle) throws -> ActionResult {
+    mutating public func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         let problems = try buildIndex()
         diagnosticEngine.emit(problems)
 

Sources/SwiftDocCUtilities/Action/Actions/Init/InitAction.swift

@@ -12,8 +12,8 @@ import Foundation
 import SwiftDocC
 
 /// An action that generates a documentation catalog from a template seed.
-public struct InitAction: Action {
-    
+public struct InitAction: AsyncAction {
+
     enum Error: DescribedError {
         case catalogAlreadyExists
         var errorDescription: String {
@@ -72,8 +72,7 @@ public struct InitAction: Action {
     /// Generates a documentation catalog from a catalog template.
     ///
     /// - Parameter logHandle: The file handle that the convert and preview actions will print debug messages to.
-    public mutating func perform(logHandle: SwiftDocC.LogHandle) throws -> ActionResult {
-        
+    public mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         let diagnosticEngine: DiagnosticEngine = DiagnosticEngine(treatWarningsAsErrors: false)
         diagnosticEngine.filterLevel = .warning
         diagnosticEngine.add(DiagnosticConsoleWriter(formattingOptions: []))

Sources/SwiftDocCUtilities/Action/Actions/Merge/MergeAction.swift

@@ -13,7 +13,7 @@ import SwiftDocC
 import Markdown
 
 /// An action that merges a list of documentation archives into a combined archive.
-struct MergeAction: Action {
+struct MergeAction: AsyncAction {
     var archives: [URL]
     var landingPageInfo: LandingPageInfo
     var outputURL: URL
@@ -33,7 +33,7 @@ struct MergeAction: Action {
         }
     }
 
-    mutating func perform(logHandle: LogHandle) throws -> ActionResult {
+    mutating func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         guard let firstArchive = archives.first else {
             // A validation warning should have already been raised in `Docc/Merge/InputAndOutputOptions/validate()`.
             return ActionResult(didEncounterError: true, outputs: [])

Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift

@@ -33,7 +33,7 @@ fileprivate func trapSignals() {
 }
 
 /// An action that monitors a documentation bundle for changes and runs a live web-preview.
-public final class PreviewAction: Action, RecreatingContext {
+public final class PreviewAction: AsyncAction {
     /// A test configuration allowing running multiple previews for concurrent testing.
     static var allowConcurrentPreviews = false
 
@@ -46,8 +46,7 @@ public final class PreviewAction: Action, RecreatingContext {
     let port: Int
 
     var convertAction: ConvertAction
-    
-    public var setupContext: ((inout DocumentationContext) -> Void)?
+
     private var previewPaths: [String] = []
 
     // Use for testing to override binding to a system port
@@ -96,7 +95,7 @@ public final class PreviewAction: Action, RecreatingContext {
     /// > Important: On macOS, the bundle will be converted each time the source is modified.
     ///
     /// - Parameter logHandle: The file handle that the convert and preview actions will print debug messages to.
-    public func perform(logHandle: LogHandle) throws -> ActionResult {
+    public func perform(logHandle: inout LogHandle) async throws -> ActionResult {
         self.logHandle = logHandle
 
         if let rootURL = convertAction.rootURL {
@@ -110,7 +109,7 @@ public final class PreviewAction: Action, RecreatingContext {
             print("Template: \(htmlTemplateDirectory.path)", to: &self.logHandle)
         }
 
-        let previewResult = try preview()
+        let previewResult = try await preview()
         return ActionResult(didEncounterError: previewResult.didEncounterError, outputs: [convertAction.targetDirectory])
     }
 
@@ -120,9 +119,9 @@ public final class PreviewAction: Action, RecreatingContext {
         servers.removeValue(forKey: serverIdentifier)
     }
 
-    func preview() throws -> ActionResult {
+    func preview() async throws -> ActionResult {
         // Convert the documentation source for previewing.
-        let result = try convert()
+        let result = try await convert()
         guard !result.didEncounterError else {
             return result
         }
@@ -163,14 +162,13 @@ public final class PreviewAction: Action, RecreatingContext {
         return previewResult
     }
 
-    func convert() throws -> ActionResult {
+    func convert() async throws -> ActionResult {
         // `cancel()` will throw `cancelPending` if there is already queued conversion.
         try convertAction.cancel()
 
         convertAction = try createConvertAction()
-        convertAction.setupContext = setupContext
 
-        let result = try convertAction.perform(logHandle: logHandle)
+        let result = try await convertAction.perform(logHandle: &logHandle)
         previewPaths = try convertAction.context.previewPaths()
         return result
     }
@@ -198,6 +196,9 @@ extension PreviewAction {
         guard let rootURL = convertAction.rootURL else {
             return
         }
+
+        var convertTask: Task<Void, any Error>?
+
         monitor = try DirectoryMonitor(root: rootURL) { _, folderURL in
             defer {
                 // Reload the directory contents and start to monitor for changes.
@@ -209,23 +210,26 @@ extension PreviewAction {
                     print(error.localizedDescription, to: &self.logHandle)
                 }
             }
-            
-            do {
-                print("Source bundle was modified, converting... ", terminator: "", to: &self.logHandle)
-                let result = try self.convert()
-                if result.didEncounterError {
-                    throw ErrorsEncountered()
+
+            print("Source bundle was modified, converting... ", terminator: "", to: &self.logHandle)
+            convertTask?.cancel()
+            convertTask = Task {
+                do {
+                    let result = try await self.convert()
+                    if result.didEncounterError {
+                        throw ErrorsEncountered()
+                    }
+                    print("Done.", to: &self.logHandle)
+                } catch ConvertAction.Error.cancelPending {
+                    // `monitor.restart()` is already queueing a new convert action which will start when the previous one completes.
+                    // We can safely ignore the current action and just log to the console.
+                    print("\nConversion already in progress...", to: &self.logHandle)
+                } catch DocumentationContext.ContextError.registrationDisabled {
+                    // The context cancelled loading the bundles and threw to yield execution early.
+                    print("\nConversion cancelled...", to: &self.logHandle)
+                } catch {
+                    print("\n\(error.localizedDescription)\nCompilation failed", to: &self.logHandle)
                 }
-                print("Done.", to: &self.logHandle)
-            } catch ConvertAction.Error.cancelPending {
-                // `monitor.restart()` is already queueing a new convert action which will start when the previous one completes.
-                // We can safely ignore the current action and just log to the console.
-                print("\nConversion already in progress...", to: &self.logHandle)
-            } catch DocumentationContext.ContextError.registrationDisabled {
-                // The context cancelled loading the bundles and threw to yield execution early.
-                print("\nConversion cancelled...", to: &self.logHandle)
-            } catch {
-                print("\n\(error.localizedDescription)\nCompilation failed", to: &self.logHandle)
             }
         }
         try monitor.start()