add experimental Doxygen support (#497)

rdar://105848459

Author: QuietMisdreavus

Package.resolved

@@ -422,7 +422,12 @@ public struct DocumentationNode {
             ]
         } else if let symbol = documentedSymbol, let docComment = symbol.docComment {
             let docCommentString = docComment.lines.map { $0.text }.joined(separator: "\n")
-            let docCommentMarkup = Document(parsing: docCommentString, options: [.parseBlockDirectives, .parseSymbolLinks])
+
+            var documentOptions: ParseOptions = [.parseBlockDirectives, .parseSymbolLinks]
+            if FeatureFlags.current.isExperimentalDoxygenSupportEnabled {
+                documentOptions.insert(.parseMinimalDoxygen)
+            }
+            let docCommentMarkup = Document(parsing: docCommentString, options: documentOptions)
 
             let docCommentDirectives = docCommentMarkup.children.compactMap({ $0 as? BlockDirective })
             if !docCommentDirectives.isEmpty {

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -25,4 +25,12 @@ public struct Parameter {
         self.name = name
         self.contents = contents
     }
+
+    /// Initialize a value to describe documentation about a symbol's parameter via a Doxygen `\param` command.
+    ///
+    /// - Parameter doxygenParameter: A parsed Doxygen `\param` command.
+    public init(_ doxygenParameter: DoxygenParameter) {
+        self.name = doxygenParameter.name
+        self.contents = Array(doxygenParameter.children)
+    }
 }

Sources/SwiftDocC/Model/Semantics/Parameter.swift

@@ -20,4 +20,11 @@ public struct Return {
     public init(contents: [Markup]) {
         self.contents = contents
     }
+
+    /// Initialize a value to describe documentation about a symbol's return value.
+    ///
+    /// - Parameter doxygenReturns: A parsed Doxygen `\returns` command.
+    public init(_ doxygenReturns: DoxygenReturns) {
+        self.contents = Array(doxygenReturns.children)
+    }
 }

Sources/SwiftDocC/Model/Semantics/Return.swift

@@ -30,6 +30,9 @@ public struct FeatureFlags: Codable {
 
     /// Whether or not experimental support for device frames on images and video is enabled.
     public var isExperimentalDeviceFrameSupportEnabled = false
+
+    /// Whether or not experimental support for parsing Doxygen commands is enabled.
+    public var isExperimentalDoxygenSupportEnabled = false
 
     /// Creates a set of feature flags with the given values.
     ///

Sources/SwiftDocC/Utility/FeatureFlags.swift

@@ -407,4 +407,14 @@ struct TaggedListItemExtractor: MarkupRewriter {
         // No match; leave this list item alone.
         return listItem
     }
+
+    mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> Markup? {
+        parameters.append(Parameter(doxygenParam))
+        return nil
+    }
+
+    mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> Markup? {
+        returns.append(Return(doxygenReturns))
+        return nil
+    }
 }

Sources/SwiftDocC/Utility/MarkupExtensions/ListItemExtractor.swift

@@ -21,6 +21,7 @@ extension ConvertAction {
         let outOfProcessResolver: OutOfProcessReferenceResolver?
 
         FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled = convert.enableExperimentalDeviceFrameSupport
+        FeatureFlags.current.isExperimentalDoxygenSupportEnabled = convert.experimentalParseDoxygenCommands
 
         // If the user-provided a URL for an external link resolver, attempt to
         // initialize an `OutOfProcessReferenceResolver` with the provided URL.

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

@@ -167,6 +167,12 @@ extension Docc {
         @OptionGroup()
         public var sourceRepositoryArguments: SourceRepositoryArguments
 
+        /// A user-provided value that is true if experimental Doxygen support should be enabled.
+        ///
+        /// Defaults to false.
+        @Flag(help: .hidden)
+        public var experimentalParseDoxygenCommands = false
+
         // MARK: - Info.plist fallbacks
 
         /// A user-provided fallback display name for the documentation bundle.

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

@@ -514,6 +514,31 @@ class SymbolTests: XCTestCase {
         XCTAssertEqual(problems.count, 0)
     }
 
+    func testParseDoxygenWithFeatureFlag() throws {
+        enableFeatureFlag(\.isExperimentalDoxygenSupportEnabled)
+
+        let deckKitSymbolGraph = Bundle.module.url(
+            forResource: "DeckKit-Objective-C",
+            withExtension: "symbols.json",
+            subdirectory: "Test Resources"
+        )!
+        let (_, _, context) = try testBundleAndContext(copying: "TestBundle") { url in
+            try? FileManager.default.copyItem(at: deckKitSymbolGraph, to: url.appendingPathComponent("DeckKit.symbols.json"))
+        }
+        let symbol = try XCTUnwrap(context.symbolIndex["c:objc(cs)PlayingCard(cm)newWithRank:ofSuit:"]?.semantic as? Symbol)
+
+        XCTAssertEqual(symbol.abstract?.format(), "Allocate and initialize a new card with the given rank and suit.")
+
+        XCTAssertEqual(symbol.parametersSection?.parameters.count, 2)
+
+        let rankParameter = try XCTUnwrap(symbol.parametersSection?.parameters.first(where:{$0.name == "rank"}))
+        XCTAssertEqual(rankParameter.contents.map({$0.format()}), ["The rank of the card."])
+        let suitParameter = try XCTUnwrap(symbol.parametersSection?.parameters.first(where:{$0.name == "suit"}))
+        XCTAssertEqual(suitParameter.contents.map({$0.format()}), ["The suit of the card."])
+
+        XCTAssertEqual(symbol.returnsSection?.content.map({ $0.format() }), ["A new card with the given configuration."])
+    }
+
     func testUnresolvedReferenceWarningsInDocumentationExtension() throws {
         let (url, _, context) = try testBundleAndContext(copying: "TestBundle") { url in
             let myKitDocumentationExtensionComment = """

Tests/SwiftDocCTests/Semantics/SymbolTests.swift

@@ -1591,14 +1591,66 @@
             "range" : {
               "end" : {
                 "character" : 68,
-                "line" : 56
+                "line" : 46
               },
               "start" : {
                 "character" : 4,
-                "line" : 56
+                "line" : 46
               }
             },
             "text" : "Allocate and initialize a new card with the given rank and suit."
+          },
+          {
+            "range" : {
+              "end" : {
+                "character" : 3,
+                "line" : 47
+              },
+              "start" : {
+                "character" : 3,
+                "line" : 47
+              }
+            },
+            "text" : ""
+          },
+          {
+            "range" : {
+              "end" : {
+                "character" : 37,
+                "line" : 48
+              },
+              "start" : {
+                "character" : 4,
+                "line" : 48
+              }
+            },
+            "text" : "\\param rank The rank of the card."
+          },
+          {
+            "range" : {
+              "end" : {
+                "character" : 37,
+                "line" : 49
+              },
+              "start" : {
+                "character" : 4,
+                "line" : 49
+              }
+            },
+            "text" : "@param suit The suit of the card."
+          },
+          {
+            "range" : {
+              "end" : {
+                "character" : 54,
+                "line" : 50
+              },
+              "start" : {
+                "character" : 4,
+                "line" : 50
+              }
+            },
+            "text" : "\\returns A new card with the given configuration. "
           }
         ]
       },

Tests/SwiftDocCTests/Test Resources/DeckKit-Objective-C.symbols.json

@@ -165,7 +165,7 @@ class ConvertSubcommandTests: XCTestCase {
             ]), "Did not refuse target folder path '\(path)'")
         }
     }
-  
+
     func testAnalyzerIsTurnedOffByDefault() throws {
         setenv(TemplateOption.environmentVariableKey, testTemplateURL.path, 1)
         let convertOptions = try Docc.Convert.parse([
@@ -206,7 +206,7 @@ class ConvertSubcommandTests: XCTestCase {
             XCTAssertEqual(convertOptions.defaultCodeListingLanguage, "swift")
         }
 
-        // Are set when passed 
+        // Are set when passed
         do {
             let convertOptions = try Docc.Convert.parse([
                 testBundleURL.path,
@@ -390,6 +390,27 @@ class ConvertSubcommandTests: XCTestCase {
         XCTAssertTrue(commandWithFlag.enableExperimentalDeviceFrameSupport)
         XCTAssertTrue(FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled)
     }
+
+    func testExperimentalParseDoxygenFlag() throws {
+        let originalFeatureFlagsState = FeatureFlags.current
+
+        defer {
+            FeatureFlags.current = originalFeatureFlagsState
+        }
+
+        let commandWithoutFlag = try Docc.Convert.parse([testBundleURL.path])
+        let _ = try ConvertAction(fromConvertCommand: commandWithoutFlag)
+        XCTAssertFalse(commandWithoutFlag.experimentalParseDoxygenCommands)
+        XCTAssertFalse(FeatureFlags.current.isExperimentalDoxygenSupportEnabled)
+
+        let commandWithFlag = try Docc.Convert.parse([
+            "--experimental-parse-doxygen-commands",
+            testBundleURL.path,
+        ])
+        let _ = try ConvertAction(fromConvertCommand: commandWithFlag)
+        XCTAssertTrue(commandWithFlag.experimentalParseDoxygenCommands)
+        XCTAssertTrue(FeatureFlags.current.isExperimentalDoxygenSupportEnabled)
+    }
 
     func testTransformForStaticHostingFlagWithoutHTMLTemplate() throws {
         unsetenv(TemplateOption.environmentVariableKey)