Add support for formatting the new Doxygen types using MarkupFormatter (#163)

* Add the new commands to the docs

* Remove duplicate code from DoxygenParameter/DoxygenReturns formatters

* Add support for formatting DoxygenDiscussion/DoxygenNote

* Add tests for DoxygenDiscussion/DoxygenNote printing

* Add a test to verify printing both Doxygen prefixes works

* Update copyright years

Author: j-f1

Sources/Markdown/Markdown.docc/Markdown/DoxygenCommands.md

@@ -44,6 +44,8 @@ Doxygen commands are not parsed within code blocks or block directive content.
 
 ### Commands
 
+- ``DoxygenDiscussion``
+- ``DoxygenNote``
 - ``DoxygenParam``
 - ``DoxygenReturns``
 

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-2023 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
@@ -1165,15 +1165,29 @@ public struct MarkupFormatter: MarkupWalker {
         }
     }
 
-    public mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> () {
-        print("\(formattingOptions.doxygenCommandPrefix.rawValue)param", for: doxygenParam)
-        print(" \(doxygenParam.name) ", for: doxygenParam)
+    private mutating func printDoxygenStart(_ name: String, for element: Markup) {
+        print(formattingOptions.doxygenCommandPrefix.rawValue + name + " ", for: element)
+    }
+
+    public mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) {
+        printDoxygenStart("discussion", for: doxygenDiscussion)
+        descendInto(doxygenDiscussion)
+    }
+
+    public mutating func visitDoxygenNote(_ doxygenNote: DoxygenNote) {
+        printDoxygenStart("note", for: doxygenNote)
+        descendInto(doxygenNote)
+    }
+
+    public mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) {
+        printDoxygenStart("param", for: doxygenParam)
+        print("\(doxygenParam.name) ", for: doxygenParam)
         descendInto(doxygenParam)
     }
 
-    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> () {
+    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) {
         // FIXME: store the actual command name used in the original markup
-        print("\(formattingOptions.doxygenCommandPrefix.rawValue)returns ", for: doxygenReturns)
+        printDoxygenStart("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-2023 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
@@ -289,6 +289,56 @@ class MarkupFormatterSingleElementTests: XCTestCase {
         XCTAssertEqual(expected, printed)
     }
 
+    func testPrintDoxygenPrefix() {
+        let expectedSlash = #"\discussion Discussion"#
+        let printedSlash = DoxygenDiscussion(children: Paragraph(Text("Discussion")))
+            .format(options: .init(doxygenCommandPrefix: .backslash))
+        XCTAssertEqual(expectedSlash, printedSlash)
+
+        let expectedAt = "@discussion Discussion"
+        let printedAt = DoxygenDiscussion(children: Paragraph(Text("Discussion")))
+            .format(options: .init(doxygenCommandPrefix: .at))
+        XCTAssertEqual(expectedAt, printedAt)
+    }
+
+    func testPrintDoxygenDiscussion() {
+        let expected = #"\discussion Another thing."#
+        let printed = DoxygenDiscussion(children: Paragraph(Text("Another thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenDiscussionMultiline() {
+        let expected = #"""
+        \discussion Another thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenDiscussion(children: Paragraph(
+            Text("Another thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenNote() {
+        let expected = #"\note Another thing."#
+        let printed = DoxygenNote(children: Paragraph(Text("Another thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenNoteMultiline() {
+        let expected = #"""
+        \note Another thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenNote(children: Paragraph(
+            Text("Another thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
+
     func testPrintDoxygenParameter() {
         let expected = #"\param thing The thing."#
         let printed = DoxygenParameter(name: "thing", children: Paragraph(Text("The thing."))).format()