add support for the Doxygen \returns command

Author: QuietMisdreavus

Sources/Markdown/Base/Markup.swift

@@ -73,6 +73,8 @@ func makeMarkup(_ data: _MarkupData) -> Markup {
         return InlineAttributes(data)
     case .doxygenParam:
         return DoxygenParam(data)
+    case .doxygenReturns:
+        return DoxygenReturns(data)
     }
 }
 

Sources/Markdown/Base/RawMarkup.swift

@@ -53,6 +53,7 @@ enum RawMarkupData: Equatable {
     case tableCell(colspan: UInt, rowspan: UInt)
 
     case doxygenParam(name: String)
+    case doxygenReturns
 }
 
 extension RawMarkupData {
@@ -336,6 +337,10 @@ final class RawMarkup: ManagedBuffer<RawMarkupHeader, RawMarkup> {
     static func doxygenParam(name: String, parsedRange: SourceRange?, _ children: [RawMarkup]) -> RawMarkup {
         return .create(data: .doxygenParam(name: name), parsedRange: parsedRange, children: children)
     }
+
+    static func doxygenReturns(parsedRange: SourceRange?, _ children: [RawMarkup]) -> RawMarkup {
+        return .create(data: .doxygenReturns, parsedRange: parsedRange, children: children)
+    }
 }
 
 fileprivate extension Sequence where Element == RawMarkup {

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

@@ -0,0 +1,58 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+/// A parsed Doxygen `\returns` command.
+///
+/// The Doxygen support in Swift-Markdown parses `\returns` commands of the form
+/// `\returns description`, where `description` continues until the next blank line or parsed
+/// command. The commands `\return` and `\result` are also accepted, with the same format.
+///
+/// ```markdown
+/// \returns A freshly-created object.
+/// ```
+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)
+        }
+        let absoluteRaw = AbsoluteRawMarkup(markup: raw, metadata: MarkupMetadata(id: .newRoot(), indexInParent: 0))
+        self.init(_MarkupData(absoluteRaw))
+    }
+
+    init(_ data: _MarkupData) {
+        self._data = data
+    }
+
+    public func accept<V: MarkupVisitor>(_ visitor: inout V) -> V.Result {
+        return visitor.visitDoxygenReturns(self)
+    }
+}
+
+public extension DoxygenReturns {
+    /// Create a new Doxygen parameter definition.
+    ///
+    /// - Parameter name: The name of the parameter being described.
+    /// - Parameter children: Block child elements.
+    init<Children: Sequence>(children: Children) where Children.Element == BlockMarkup {
+        try! self.init(.doxygenReturns(parsedRange: nil, children.map({ $0.raw.markup })))
+    }
+
+    /// Create a new Doxygen parameter definition.
+    ///
+    /// - Parameter name: The name of the parameter being described.
+    /// - Parameter children: Block child elements.
+    init(children: BlockMarkup...) {
+        self.init(children: children)
+    }
+}

Sources/Markdown/Parser/BlockDirectiveParser.swift

@@ -226,11 +226,14 @@ struct PendingBlockDirective {
 struct PendingDoxygenCommand {
     enum CommandKind {
         case param(name: Substring)
+        case returns
 
         var debugDescription: String {
             switch self {
             case .param(name: let name):
                 return "'param' Argument: '\(name)'"
+            case .returns:
+                return "'returns'"
             }
         }
     }
@@ -730,6 +733,8 @@ private enum ParseContainer: CustomStringConvertible {
             switch pendingDoxygenCommand.kind {
             case .param(let name):
                 return [.doxygenParam(name: String(name), parsedRange: range, children)]
+            case .returns:
+                return [.doxygenReturns(parsedRange: range, children)]
             }
         }
     }
@@ -870,6 +875,14 @@ struct ParseContainerStack {
                 endLocation: name.range!.upperBound)
             pendingCommand.addLine(remainder)
             return (pendingCommand, remainder)
+        case "return", "returns", "result":
+            var pendingCommand = PendingDoxygenCommand(
+                atLocation: at.range!.lowerBound,
+                nameLocation: name.range!.lowerBound,
+                kind: .returns,
+                endLocation: name.range!.upperBound)
+            pendingCommand.addLine(remainder)
+            return (pendingCommand, remainder)
         default:
             return nil
         }

Sources/Markdown/Visitor/MarkupVisitor.swift

@@ -282,6 +282,14 @@ public protocol MarkupVisitor {
      - returns: The result of the visit.
      */
     mutating func visitDoxygenParam(_ doxygenParam: DoxygenParam) -> Result
+
+    /**
+     Visit a `DoxygenReturns` element and return the result.
+
+     - parameter doxygenReturns: A `DoxygenReturns` element.
+     - returns: The result of the visit.
+     */
+    mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> Result
 }
 
 extension MarkupVisitor {
@@ -384,4 +392,7 @@ extension MarkupVisitor {
     public mutating func visitDoxygenParam(_ doxygenParam: DoxygenParam) -> Result {
         return defaultVisit(doxygenParam)
     }
+    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> Result {
+        return defaultVisit(doxygenReturns)
+    }
 }

Tests/MarkdownTests/Parsing/DoxygenCommandParserTests.swift

@@ -32,6 +32,28 @@ class DoxygenCommandParserTests: XCTestCase {
         XCTAssertEqual(document.debugDescription(), expectedDump)
     }
 
+    func testParseReturns() {
+        func assertValidParse(source: String) {
+            let document = Document(parsing: source, options: parseOptions)
+            XCTAssert(document.child(at: 0) is DoxygenReturns)
+
+            let expectedDump = """
+            Document
+            └─ DoxygenReturns
+               └─ Paragraph
+                  └─ Text "The thing."
+            """
+            XCTAssertEqual(document.debugDescription(), expectedDump)
+        }
+
+        assertValidParse(source: "@returns The thing.")
+        assertValidParse(source: "@return The thing.")
+        assertValidParse(source: "@result The thing.")
+        assertValidParse(source: #"\returns The thing."#)
+        assertValidParse(source: #"\return The thing."#)
+        assertValidParse(source: #"\result The thing."#)
+    }
+
     func testParseParamWithSlash() throws {
         let source = #"""
         \param thing The thing.