Strip Leading Whitespace From Symbol Graph Doc Comments (#1190)

* Strip the minimum leading whitespace from all doc comments loaded from
symbol graphs. This worksaround a Clang compiler issue with parsing
comments like this that are missing the leading asterisk:

/**
 Foo's brief description.

 Foo's discussion.
*/

...as opposed to this which Clang does parse properly:

/**
* Foo's brief description.
*
* Foo's discussion.
*/

"Minumum leading whitespace" is defined as:
- Find the doc comment 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).

* Update Sources/SwiftDocC/Model/DocumentationNode.swift

Refactor a loop to use `contains(where:)`

Co-authored-by: David Rönnqvist <[email protected]>

* [String].linesWithoutLeadingWhitespace returns an array
of substrings, not strings.

* [String].linesWithoutLeadingWhitespace checks for an empty collection
before continuing to parse all the lines

* Tweak comments

---------

Co-authored-by: David Rönnqvist <[email protected]>

Author: patshaughnessy

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,40 @@ private extension BlockDirective {
         directivesSupportedInDocumentationComments.contains(name)
     }
 }
+
+extension [String] {
+
+    /// Strip the minimum leading whitespace from all the strings in this array, as follows:
+    /// - 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(