add initial support for Doxygen \param command

rdar://69835334

Author: QuietMisdreavus

Sources/Markdown/Base/Markup.swift

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

Sources/Markdown/Base/RawMarkup.swift

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

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

@@ -0,0 +1,78 @@
+/*
+ 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 `\param` command.
+///
+/// The Doxygen support in Swift-Markdown parses `\param` commands of the form
+/// `\param name description`, where `description` extends until the next blank line or the next
+/// parsed command. For example, the following input will return two `DoxygenParam` instances:
+///
+/// ```markdown
+/// \param coordinate The coordinate used to center the transformation.
+/// \param matrix The transformation matrix that describes the transformation.
+/// For more information about transformation matrices, refer to the Transformation
+/// documentation.
+/// ```
+public struct DoxygenParam: 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.visitDoxygenParam(self)
+    }
+}
+
+public extension DoxygenParam {
+    /// Create a new Doxygen parameter definition.
+    ///
+    /// - Parameter name: The name of the parameter being described.
+    /// - Parameter children: Block child elements.
+    init<Children: Sequence>(name: String, children: Children) where Children.Element == BlockMarkup {
+        try! self.init(.doxygenParam(name: name, 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(name: String, children: BlockMarkup...) {
+        self.init(name: name, children: children)
+    }
+
+    /// The name of the parameter being described.
+    var name: String {
+        get {
+            guard case let .doxygenParam(name) = _data.raw.markup.data else {
+                fatalError("\(self) markup wrapped unexpected \(_data.raw)")
+            }
+            return name
+        }
+        set {
+            _data = _data.replacingSelf(.doxygenParam(
+                name: newValue,
+                parsedRange: nil,
+                _data.raw.markup.copyChildren()
+            ))
+        }
+    }
+}

Sources/Markdown/Parser/BlockDirectiveParser.swift

@@ -223,6 +223,31 @@ struct PendingBlockDirective {
     }
 }
 
+struct PendingDoxygenCommand {
+    enum CommandKind {
+        case param(name: Substring)
+
+        var debugDescription: String {
+            switch self {
+            case .param(name: let name):
+                return "'param' Argument: '\(name)'"
+            }
+        }
+    }
+
+    var atLocation: SourceLocation
+
+    var nameLocation: SourceLocation
+
+    var kind: CommandKind
+
+    var endLocation: SourceLocation
+
+    mutating func addLine(_ line: TrimmedLine) {
+        endLocation = SourceLocation(line: line.lineNumber ?? 0, column: line.untrimmedText.count + 1, source: line.source)
+    }
+}
+
 struct TrimmedLine {
     /// A successful result of scanning for a prefix on a ``TrimmedLine``.
     struct Lex: Equatable {
@@ -459,8 +484,11 @@ private enum ParseContainer: CustomStringConvertible {
     /// A block directive container, which can contain other block directives or runs of lines.
     case blockDirective(PendingBlockDirective, [ParseContainer])
 
-    init<TrimmedLines: Sequence>(parsingHierarchyFrom trimmedLines: TrimmedLines) where TrimmedLines.Element == TrimmedLine {
-        self = ParseContainerStack(parsingHierarchyFrom: trimmedLines).top
+    /// A Doxygen command, which can contain arbitrary markup (but not block directives).
+    case doxygenCommand(PendingDoxygenCommand, [TrimmedLine])
+
+    init<TrimmedLines: Sequence>(parsingHierarchyFrom trimmedLines: TrimmedLines, options: ParseOptions) where TrimmedLines.Element == TrimmedLine {
+        self = ParseContainerStack(parsingHierarchyFrom: trimmedLines, options: options).top
     }
 
     var children: [ParseContainer] {
@@ -471,6 +499,8 @@ private enum ParseContainer: CustomStringConvertible {
             return children
         case .lineRun:
             return []
+        case .doxygenCommand:
+            return []
         }
     }
 
@@ -545,6 +575,15 @@ private enum ParseContainer: CustomStringConvertible {
                     indent -= 4
                 }
                 print(children: children)
+            case .doxygenCommand(let pendingDoxygenCommand, let lines):
+                print("* Doxygen command \(pendingDoxygenCommand.kind.debugDescription)")
+                queueNewline()
+                indent += 4
+                for line in lines {
+                    print(line.text.debugDescription)
+                    queueNewline()
+                }
+                indent -= 4
             }
         }
     }
@@ -565,6 +604,9 @@ private enum ParseContainer: CustomStringConvertible {
         case .blockDirective(var pendingBlockDirective, let children):
             pendingBlockDirective.updateIndentation(for: line)
             self = .blockDirective(pendingBlockDirective, children)
+        case .doxygenCommand:
+            var newParent: ParseContainer? = nil
+            parent?.updateIndentation(under: &newParent, for: line)
         }
     }
 
@@ -609,6 +651,8 @@ private enum ParseContainer: CustomStringConvertible {
             return parent?.indentationAdjustment(under: nil) ?? 0
         case .blockDirective(let pendingBlockDirective, _):
             return pendingBlockDirective.indentationColumnCount
+        case .doxygenCommand:
+            return parent?.indentationAdjustment(under: nil) ?? 0
         }
     }
 
@@ -677,6 +721,15 @@ private enum ParseContainer: CustomStringConvertible {
                                     }),
                                     parsedRange: pendingBlockDirective.atLocation..<pendingBlockDirective.endLocation,
                                     children)]
+        case let .doxygenCommand(pendingDoxygenCommand, lines):
+            let range = pendingDoxygenCommand.atLocation..<pendingDoxygenCommand.endLocation
+            ranges.add(range)
+            let children = ParseContainer.lineRun(lines, isInCodeFence: false)
+                .convertToRawMarkup(ranges: &ranges, parent: self, options: options)
+            switch pendingDoxygenCommand.kind {
+            case .param(let name):
+                return [.doxygenParam(name: String(name), parsedRange: range, children)]
+            }
         }
     }
 }
@@ -689,8 +742,11 @@ struct ParseContainerStack {
     /// The stack of containers to be incrementally folded into a hierarchy.
     private var stack: [ParseContainer]
 
-    init<TrimmedLines: Sequence>(parsingHierarchyFrom trimmedLines: TrimmedLines) where TrimmedLines.Element == TrimmedLine {
+    private let options: ParseOptions
+
+    init<TrimmedLines: Sequence>(parsingHierarchyFrom trimmedLines: TrimmedLines, options: ParseOptions) where TrimmedLines.Element == TrimmedLine {
         self.stack = [.root([])]
+        self.options = options
         for line in trimmedLines {
             accept(line)
         }
@@ -708,6 +764,20 @@ struct ParseContainerStack {
         } != nil
     }
 
+    private var canParseDoxygenCommand: Bool {
+        guard options.contains(.parseMinimalDoxygen) else { return false }
+
+        guard !isInBlockDirective else { return false }
+
+        if case .blockDirective = top {
+            return false
+        } else if case .lineRun(_, isInCodeFence: let codeFence) = top {
+            return !codeFence
+        } else {
+            return true
+        }
+    }
+
     private func isCodeFenceOrIndentedCodeBlock(on line: TrimmedLine) -> Bool {
         // Check if this line is indented 4 or more spaces relative to the current
         // indentation adjustment.
@@ -760,23 +830,85 @@ struct ParseContainerStack {
         return pendingBlockDirective
     }
 
+    private func parseDoxygenCommandOpening(on line: TrimmedLine) -> (pendingCommand: PendingDoxygenCommand, remainder: TrimmedLine)? {
+        guard canParseDoxygenCommand else { return nil }
+        guard !isCodeFenceOrIndentedCodeBlock(on: line) else { return nil }
+
+        var remainder = line
+        guard let at = remainder.lex(until: { ch in
+            switch ch {
+            case "@", "\\":
+                return .continue
+            default:
+                return .stop
+            }
+        }) else { return nil }
+        guard let name = remainder.lex(until: { ch in
+            if ch.isWhitespace {
+                return .stop
+            } else {
+                return .continue
+            }
+        }) else { return nil }
+        remainder.lexWhitespace()
+
+        switch name.text.lowercased() {
+        case "param":
+            guard let paramName = remainder.lex(until: { ch in
+                if ch.isWhitespace {
+                    return .stop
+                } else {
+                    return .continue
+                }
+            }) else { return nil }
+            remainder.lexWhitespace()
+            var pendingCommand = PendingDoxygenCommand(
+                atLocation: at.range!.lowerBound,
+                nameLocation: name.range!.lowerBound,
+                kind: .param(name: paramName.text),
+                endLocation: name.range!.upperBound)
+            pendingCommand.addLine(remainder)
+            return (pendingCommand, remainder)
+        default:
+            return nil
+        }
+    }
+
     /// Accept a trimmed line, opening new block directives as indicated by the source,
     /// closing a block directive if applicable, or adding the line to a run of lines to be parsed
     /// as Markdown later.
     private mutating func accept(_ line: TrimmedLine) {
-        if line.isEmptyOrAllWhitespace,
-           case let .blockDirective(pendingBlockDirective, _) = top {
-            switch pendingBlockDirective.parseState {
-            case .argumentsStart,
-                 .contentsStart,
-                 .done:
-                closeTop()
+        if line.isEmptyOrAllWhitespace {
+            switch top {
+            case let .blockDirective(pendingBlockDirective, _):
+                switch pendingBlockDirective.parseState {
+                case .argumentsStart,
+                     .contentsStart,
+                     .done:
+                    closeTop()
 
+                default:
+                    break
+                }
+            case .doxygenCommand:
+                closeTop()
             default:
                 break
             }
         }
 
+        // If we can parse a Doxygen command from this line, start one and skip everything else.
+        if let result = parseDoxygenCommandOpening(on: line) {
+            switch top {
+            case .root:
+                break
+            default:
+                closeTop()
+            }
+            push(.doxygenCommand(result.pendingCommand, [result.remainder]))
+            return
+        }
+
         // If we're inside a block directive, check to see whether we need to update its
         // indentation calculation to account for its content.
         updateIndentation(for: line)
@@ -822,7 +954,7 @@ struct ParseContainerStack {
             switch top {
             case .root:
                 push(.blockDirective(newBlockDirective, []))
-            case .lineRun:
+            case .lineRun, .doxygenCommand:
                 closeTop()
                 push(.blockDirective(newBlockDirective, []))
             case .blockDirective(let previousBlockDirective, _):
@@ -848,11 +980,16 @@ struct ParseContainerStack {
         } else {
             switch top {
             case .root:
-                push(.lineRun([line], isInCodeFence: false))
+                push(.lineRun([line], isInCodeFence: line.isProbablyCodeFence))
             case .lineRun(var lines, let isInCodeFence):
                 pop()
                 lines.append(line)
                 push(.lineRun(lines, isInCodeFence: isInCodeFence != line.isProbablyCodeFence))
+            case .doxygenCommand(var pendingDoxygenCommand, var lines):
+                pop()
+                lines.append(line)
+                pendingDoxygenCommand.addLine(line)
+                push(.doxygenCommand(pendingDoxygenCommand, lines))
             case .blockDirective(var pendingBlockDirective, let children):
                 // A pending block directive can accept this line if it is in the middle of
                 // parsing arguments text (to allow indentation to align arguments) or
@@ -923,6 +1060,8 @@ struct ParseContainerStack {
             push(.blockDirective(pendingBlockDirective, children))
         case .lineRun:
             fatalError("Line runs cannot have children")
+        case .doxygenCommand:
+            fatalError("Doxygen commands cannot have children")
         }
     }
 
@@ -985,7 +1124,7 @@ struct BlockDirectiveParser {
         // Phase 1: Categorize the lines into a hierarchy of block containers by parsing the prefix
         // of the line, opening and closing block directives appropriately, and folding elements
         // into a root document.
-        let rootContainer = ParseContainer(parsingHierarchyFrom: trimmedLines)
+        let rootContainer = ParseContainer(parsingHierarchyFrom: trimmedLines, options: options)
 
         // Phase 2: Convert the hierarchy of block containers into a real ``Document``.
         // This is where the CommonMark parser is called upon to parse runs of lines of content,

Sources/Markdown/Parser/ParseOptions.swift

@@ -24,5 +24,8 @@ public struct ParseOptions: OptionSet {
 
     /// Disable converting straight quotes to curly, --- to em dashes, -- to en dashes during parsing
     public static let disableSmartOpts = ParseOptions(rawValue: 1 << 2)
+
+    /// Parse a limited set of Doxygen commands. Requires ``parseBlockDirectives``.
+    public static let parseMinimalDoxygen = ParseOptions(rawValue: 1 << 3)
 }