support doxygen param/returns in MarkupFormatter

Author: QuietMisdreavus

Sources/Markdown/Block Nodes/Block Container Blocks/Doxygen Commands/DoxygenParameter.swift

@@ -27,7 +27,7 @@ public struct DoxygenParameter: BlockContainer {
 
     init(_ raw: RawMarkup) throws {
         guard case .doxygenParam = raw.data else {
-            throw RawMarkup.Error.concreteConversionError(from: raw, to: BlockDirective.self)
+            throw RawMarkup.Error.concreteConversionError(from: raw, to: DoxygenParameter.self)
         }
         let absoluteRaw = AbsoluteRawMarkup(markup: raw, metadata: MarkupMetadata(id: .newRoot(), indexInParent: 0))
         self.init(_MarkupData(absoluteRaw))

Sources/Markdown/Block Nodes/Block Container Blocks/Doxygen Commands/DoxygenReturns.swift

@@ -23,8 +23,8 @@ public struct DoxygenReturns: BlockContainer {
     public var _data: _MarkupData
 
     init(_ raw: RawMarkup) throws {
-        guard case .doxygenParam = raw.data else {
-            throw RawMarkup.Error.concreteConversionError(from: raw, to: BlockDirective.self)
+        guard case .doxygenReturns = raw.data else {
+            throw RawMarkup.Error.concreteConversionError(from: raw, to: DoxygenReturns.self)
         }
         let absoluteRaw = AbsoluteRawMarkup(markup: raw, metadata: MarkupMetadata(id: .newRoot(), indexInParent: 0))
         self.init(_MarkupData(absoluteRaw))

Sources/Markdown/Walker/Walkers/MarkupFormatter.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-2023 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
@@ -230,6 +230,15 @@ public struct MarkupFormatter: MarkupWalker {
             }
         }
 
+        /// The character to use when formatting Doxygen commands.
+        public enum DoxygenCommandPrefix: String, CaseIterable {
+            /// Precede Doxygen commands with a backslash (`\`).
+            case backslash = "\\"
+
+            /// Precede Doxygen commands with an at-sign (`@`).
+            case at = "@"
+        }
+
         // MARK: Option Properties
 
         var orderedListNumerals: OrderedListNumerals
@@ -243,6 +252,7 @@ public struct MarkupFormatter: MarkupWalker {
         var preferredHeadingStyle: PreferredHeadingStyle
         var preferredLineLimit: PreferredLineLimit?
         var customLinePrefix: String
+        var doxygenCommandPrefix: DoxygenCommandPrefix
 
         /**
          Create a set of formatting options to use when printing an element.
@@ -270,7 +280,8 @@ public struct MarkupFormatter: MarkupWalker {
                     condenseAutolinks: Bool = true,
                     preferredHeadingStyle: PreferredHeadingStyle = .atx,
                     preferredLineLimit: PreferredLineLimit? = nil,
-                    customLinePrefix: String = "") {
+                    customLinePrefix: String = "",
+                    doxygenCommandPrefix: DoxygenCommandPrefix = .backslash) {
             self.unorderedListMarker = unorderedListMarker
             self.orderedListNumerals = orderedListNumerals
             self.useCodeFence = useCodeFence
@@ -284,6 +295,7 @@ public struct MarkupFormatter: MarkupWalker {
             // three characters long.
             self.thematicBreakLength = max(3, thematicBreakLength)
             self.customLinePrefix = customLinePrefix
+            self.doxygenCommandPrefix = doxygenCommandPrefix
         }
 
         /// The default set of formatting options.
@@ -1144,4 +1156,16 @@ public struct MarkupFormatter: MarkupWalker {
             printInlineAttributes()
         }
     }
+
+    public mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> () {
+        print("\(formattingOptions.doxygenCommandPrefix.rawValue)param", for: doxygenParam)
+        print(" \(doxygenParam.name) ", for: doxygenParam)
+        descendInto(doxygenParam)
+    }
+
+    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> () {
+        // FIXME: store the actual command name used in the original markup
+        print("\(formattingOptions.doxygenCommandPrefix.rawValue)returns ", for: doxygenReturns)
+        descendInto(doxygenReturns)
+    }
 }

Tests/MarkdownTests/Visitors/MarkupFormatterTests.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-2023 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
@@ -288,6 +288,44 @@ class MarkupFormatterSingleElementTests: XCTestCase {
         let printed = SymbolLink(destination: "foo()").format()
         XCTAssertEqual(expected, printed)
     }
+
+    func testPrintDoxygenParameter() {
+        let expected = #"\param thing The thing."#
+        let printed = DoxygenParameter(name: "thing", children: Paragraph(Text("The thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenParameterMultiline() {
+        let expected = #"""
+        \param thing The thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenParameter(name: "thing", children: Paragraph(
+            Text("The thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenReturns() {
+        let expected = #"\returns Another thing."#
+        let printed = DoxygenReturns(children: Paragraph(Text("Another thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenReturnsMultiline() {
+        let expected = #"""
+        \returns Another thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenReturns(children: Paragraph(
+            Text("Another thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
 }
 
 /// Tests that formatting options work correctly.
@@ -469,6 +507,23 @@ class MarkupFormatterOptionsTests: XCTestCase {
             XCTAssertEqual(incrementing, printed)
         }
     }
+
+    func testDoxygenCommandPrefix() {
+        let backslash = #"\param thing The thing."#
+        let at = "@param thing The thing."
+
+        do {
+            let document = Document(parsing: backslash, options: [.parseMinimalDoxygen, .parseBlockDirectives])
+            let printed = document.format(options: .init(doxygenCommandPrefix: .at))
+            XCTAssertEqual(at, printed)
+        }
+
+        do {
+            let document = Document(parsing: at, options: [.parseMinimalDoxygen, .parseBlockDirectives])
+            let printed = document.format(options: .init(doxygenCommandPrefix: .backslash))
+            XCTAssertEqual(backslash, printed)
+        }
+    }
 }
 
 /// Tests that an printed and reparsed element has the same structure as
@@ -646,7 +701,8 @@ class MarkupFormatterSimpleRoundTripTests: XCTestCase {
         let document = try Document(parsing: readMeURL)
 //        try document.format().write(toFile: "/tmp/test.md", atomically: true, encoding: .utf8)
         checkRoundTrip(for: document)
-    }}
+    }
+}
 
 /**
  Test enforcement of a preferred maximum line length.