Deprecate additionalSymbolGraphFiles (#777)

Author: d-ronnqvist

Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift

@@ -41,7 +41,7 @@ extension ConvertAction {
         // into a dictionary. This will throw with a descriptive error upon failure.
         let parsedPlatforms = try PlatformArgumentParser.parse(convert.platforms)
 
-        let additionalSymbolGraphFiles = convert.additionalSymbolGraphFiles + symbolGraphFiles(
+        let additionalSymbolGraphFiles = (convert as _DeprecatedSymbolGraphFilesAccess).additionalSymbolGraphFiles + symbolGraphFiles(
             in: convert.additionalSymbolGraphDirectory
         )
 
@@ -100,3 +100,8 @@ private func symbolGraphFiles(in directory: URL?) -> [URL] {
     return subpaths.map { directory.appendingPathComponent($0) }
         .filter { DocumentationBundleFileTypes.isSymbolGraphFile($0) }
 }
+
+private protocol _DeprecatedSymbolGraphFilesAccess {
+    var additionalSymbolGraphFiles: [URL] { get }
+}
+extension Docc.Convert: _DeprecatedSymbolGraphFilesAccess {}

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

@@ -68,6 +68,7 @@ extension Docc {
                 help: .hidden,
                 transform: URL.init(fileURLWithPath:)
             )
+            @available(*, deprecated, renamed: "additionalSymbolGraphDirectory", message: "Use 'additionalSymbolGraphDirectory' instead. This deprecated API will be removed after 5.12 is released")
             var additionalSymbolGraphFiles: [URL] = [] // Remove when other tools no longer use it. (rdar://72449411)
 
             @Option(
@@ -107,7 +108,7 @@ extension Docc {
             set { inputsAndOutputs.additionalSymbolGraphDirectory = newValue }
         }
 
-        /// A user-provided list o path to additional symbol graph files that the convert action will process.
+        @available(*, deprecated, renamed: "additionalSymbolGraphDirectory", message: "Use 'additionalSymbolGraphDirectory' instead. This deprecated API will be removed after 5.12 is released")
         public var additionalSymbolGraphFiles: [URL] { // Remove when other tools no longer use it. (rdar://72449411)
             get { inputsAndOutputs.additionalSymbolGraphFiles }
             set { inputsAndOutputs.additionalSymbolGraphFiles = newValue }

Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift

@@ -222,6 +222,9 @@ class ConvertSubcommandTests: XCTestCase {
         }
     }
 
+    // This test calls ``ConvertOptions.additionalSymbolGraphFiles`` which is deprecated.
+    // Deprecating the test silences the deprecation warning when running the tests. It doesn't skip the test.
+    @available(*, deprecated)
     func testAdditionalSymbolGraphFiles() throws {
         SetEnvironmentVariable(TemplateOption.environmentVariableKey, testTemplateURL.path)