Fix returns/throws description with empty first line

Closes #213

Author: dduan

CHANGELOG.md

@@ -2,15 +2,19 @@
 
 ## 0.5.0
 
-### Improvement (breaking change?)
+### New
 
 - `drstring check` now reports each problem it finds with a file path, line, and column, as apposed to before,
   where all problems for a specific signature are grouped together. Each type of problem has a custom column
   position to best indicate which part of the docstring it relates to.
 - `drstring extract`'s output for existing docstrings gained a new field `relativeLineNumber` for each
   "entry".
+
+### Bug fixes
 - In grouped parameter style, spacing between the dash `-` and the parameter was not checked before. From this
   release on, any spacing except a single space is deemed problematic. (#225)
+- If documentation for throws and returns starts on the second line, previously this was considered
+  problematic. But it's pretty common to start on the next line. This bug has been fixed. (#213)
 
 ## 0.4.3
 

Sources/Critic/Validating.swift

@@ -142,12 +142,12 @@ func findReturnsProblems(
         column += 1
     }
 
-    if let postColonLead = returnsDoc.description.first?.lead {
-        if postColonLead != " " {
-            result.append((.init(lineNumber, column), .spaceAfterColon(keywordText, postColonLead)))
+    if let firstLine = returnsDoc.description.first {
+        if firstLine.lead != " " && !firstLine.text.isEmpty {
+            result.append((.init(lineNumber, column), .spaceAfterColon(keywordText, firstLine.lead)))
         }
 
-        column += postColonLead.count
+        column += firstLine.lead.count
     }
 
     if alignAfterColon {
@@ -225,12 +225,12 @@ func findThrowsProblems(
         column += 1
     }
 
-    if let postColonLead = throwsDoc.description.first?.lead {
-        if postColonLead != " " {
-            result.append((.init(lineNumber, column), .spaceAfterColon(keywordText, postColonLead)))
+    if let firstLine = throwsDoc.description.first {
+        if firstLine.lead != " " && !firstLine.text.isEmpty {
+            result.append((.init(lineNumber, column), .spaceAfterColon(keywordText, firstLine.lead)))
         }
 
-        column += postColonLead.count
+        column += firstLine.lead.count
     }
 
     if alignAfterColon {

Tests/DrStringCoreTests/Fixtures/throwDescriptionNextLine.fixture

@@ -0,0 +1,11 @@
+// CHECK-NOT: warning
+/// - Throws:
+///     - Error1 when x
+///     - Error2 when y
+func f() throws {}
+
+// CHECK-NOT: warning
+/// - Returns:
+///     - 1 when x
+///     - 0 when y
+func g() -> Int {}

Tests/DrStringCoreTests/ProblemCheckingTests.swift

@@ -135,4 +135,8 @@ final class ProblemCheckingTests: XCTestCase {
             runTest(fileName: "positional", alignAfterColon: [.parameters, .returns, .throws],
                     needsSeparation: [.description, .parameters]))
     }
+
+    func testThrowsWithDescriptionStartingFromNextLine() throws {
+        XCTAssert(runTest(fileName: "throwDescriptionNextLine", expectEmpty: true))
+    }
 }

Tests/DrStringCoreTests/XCTestManifests.swift

@@ -78,6 +78,7 @@ extension ProblemCheckingTests {
         ("testRedundantKeywordsPathsOnly", testRedundantKeywordsPathsOnly),
         ("testSeparateLineInThrowsIsNotTreatedAsContinuedBody", testSeparateLineInThrowsIsNotTreatedAsContinuedBody),
         ("testSeparateParameterStyle", testSeparateParameterStyle),
+        ("testThrowsWithDescriptionStartingFromNextLine", testThrowsWithDescriptionStartingFromNextLine),
         ("testUppercaseKeywords", testUppercaseKeywords),
         ("testWhateverParameterStyle", testWhateverParameterStyle),
     ]