[6.2] Strip Leading Whitespace From Symbol Graph Doc Comments

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -523,7 +523,10 @@ public struct DocumentationNode {
                 DocumentationChunk(source: .documentationExtension, markup: documentationExtensionMarkup)
             ]
         } else if let symbol = documentedSymbol, let docComment = symbol.docComment {
-            let docCommentString = docComment.lines.map { $0.text }.joined(separator: "\n")
+            let docCommentString = docComment.lines
+                                             .map(\.text)
+                                             .linesWithoutLeadingWhitespace()
+                                             .joined(separator: "\n")
 
             let docCommentLocation: SymbolGraph.Symbol.Location? = {
                 if let uri = docComment.uri, let position = docComment.lines.first?.range?.start {
@@ -849,3 +852,42 @@ private extension BlockDirective {
         directivesSupportedInDocumentationComments.contains(name)
     }
 }
+
+extension [String] {
+
+    /// Strips the minimum leading whitespace from all the strings in the array.
+    ///
+    /// The method does the following:
+    /// - Find the line with least amount of leading whitespace. Ignore blank lines during this search.
+    /// - Remove that number of whitespace chars from all the lines (including blank lines).
+    /// - Returns: An array of substrings of the original lines with the minimum leading whitespace removed.
+    func linesWithoutLeadingWhitespace() -> [Substring] {
+
+        // Optimization for the common case: If any of the lines does not start
+        // with whitespace, or if there are no lines, then return the original lines
+        // as substrings.
+        if isEmpty || contains(where: { $0.first?.isWhitespace == false }) {
+            return self.map{ .init($0) }
+        }
+
+        /// - Count the leading whitespace characters in the given string.
+        /// - Returns: The count of leading whitespace characters, if the string is not blank,
+        ///     or `nil` if the string is empty or blank (contains only whitespace)
+        func leadingWhitespaceCount(_ line: String) -> Int? {
+            let count = line.prefix(while: \.isWhitespace).count
+            guard count < line.count else { return nil }
+            return count
+        }
+
+        // Find the minimum count of leading whitespace. If there are no
+        // leading whitespace counts (if all the lines were blank) then return
+        // the original lines as substrings.
+        guard let minimumWhitespaceCount = self.compactMap(leadingWhitespaceCount).min() else {
+            return self.map{ .init($0) }
+        }
+
+        // Drop the leading whitespace from all the lines and return the
+        // modified lines as substrings of the original lines.
+        return self.map { $0.dropFirst(minimumWhitespaceCount) }
+    }
+}

Tests/SwiftDocCTests/Semantics/SymbolTests.swift

@@ -1352,6 +1352,158 @@ class SymbolTests: XCTestCase {
         XCTAssert(problems.isEmpty)
     }
 
+    // MARK: - Leading Whitespace in Doc Comments
+
+    func testWithoutLeadingWhitespace() {
+        let lines = [
+            "One",
+            "Two Words",
+            "With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "One",
+            "Two Words",
+            "With Trailing Whitespace "
+        ]
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithLeadingWhitespace() {
+        let lines = [
+            "    One",
+            "    Two Words",
+            "    With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "One",
+            "Two Words",
+            "With Trailing Whitespace "
+        ]
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithIncreasingLeadingWhitespace() {
+        let lines = [
+            " One",
+            "  Two Words",
+            "   With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "One",
+            " Two Words",
+            "  With Trailing Whitespace "
+        ]
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithDecreasingLeadingWhitespace() {
+        let lines = [
+            "   One",
+            "  Two Words",
+            " With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "  One",
+            " Two Words",
+            "With Trailing Whitespace "
+        ]
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithoutLeadingWhitespaceBlankLines() {
+        let lines = [
+            "    One",
+            "      ",
+            "    Two Words",
+            "    ",
+            "    With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "One",
+            "  ",
+            "Two Words",
+            "",
+            "With Trailing Whitespace "
+        ]
+
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithoutLeadingWhitespaceEmptyLines() {
+        let lines = [
+            "    One",
+            "",
+            "    Two Words",
+            "",
+            "    With Trailing Whitespace "
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "One",
+            "",
+            "Two Words",
+            "",
+            "With Trailing Whitespace "
+        ]
+
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithoutLeadingWhitespaceAllEmpty() {
+        let lines = [
+            "",
+            "",
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "",
+            "",
+        ]
+
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithoutLeadingWhitespaceAllBlank() {
+        let lines = [
+            "   ",
+            "  ",
+        ]
+        let linesWithoutLeadingWhitespace: [Substring] = [
+            "   ",
+            "  ",
+        ]
+
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testWithoutLeadingWhitespaceEmpty() {
+        let lines = [String]()
+        let linesWithoutLeadingWhitespace = [Substring]()
+
+        XCTAssertEqual(lines.linesWithoutLeadingWhitespace(), linesWithoutLeadingWhitespace)
+    }
+
+    func testLeadingWhitespaceInDocComment() throws {
+        let (semanticWithLeadingWhitespace, problems) = try makeDocumentationNodeSymbol(
+            docComment: """
+                    This is an abstract.
+
+                    This is a multi-paragraph overview.
+
+                    It continues here.
+                """,
+            articleContent: nil
+        )
+        XCTAssert(problems.isEmpty)
+        XCTAssertEqual(semanticWithLeadingWhitespace.abstract?.format(), "This is an abstract.")
+        let lines = semanticWithLeadingWhitespace.discussion?.content.map{ $0.format() } ?? []
+        let expectedDiscussion = """
+            This is a multi-paragraph overview.
+
+            It continues here.
+            """
+        XCTAssertEqual(lines.joined(), expectedDiscussion)
+    }
+
+
     // MARK: - Helpers
 
     func makeDocumentationNodeForSymbol(