Merge pull request #225 from dylansturg/never_doesnt_return

Don't require a returns comment for functions that never return.

Author: allevato

Sources/SwiftFormatRules/ValidateDocumentationComments.swift

@@ -96,7 +96,12 @@ public final class ValidateDocumentationComments: SyntaxLintRule {
   ) {
     if returnClause == nil && returnDesc != nil {
       diagnose(.removeReturnComment(funcName: name), on: node)
-    } else if returnClause != nil && returnDesc == nil {
+    } else if let returnClause = returnClause, returnDesc == nil {
+      if let returnTypeIdentifier = returnClause.returnType.as(SimpleTypeIdentifierSyntax.self),
+         returnTypeIdentifier.name.text == "Never"
+      {
+        return
+      }
       diagnose(.documentReturnValue(funcName: name), on: returnClause)
     }
   }

Tests/SwiftFormatRulesTests/ValidateDocumentationCommentsTests.swift

@@ -117,10 +117,29 @@ final class ValidateDocumentationCommentsTests: LintOrFormatRuleTestCase {
     ///   - p2: Parameter 2.
     ///   - p3: Parameter 3.
     func foo(p1: Int, p2: Int, p3: Int) -> Int {}
+
+    /// One sentence summary.
+    ///
+    /// - Parameters:
+    ///   - p1: Parameter 1.
+    ///   - p2: Parameter 2.
+    ///   - p3: Parameter 3.
+    func neverReturns(p1: Int, p2: Int, p3: Int) -> Never {}
+
+    /// One sentence summary.
+    ///
+    /// - Parameters:
+    ///   - p1: Parameter 1.
+    ///   - p2: Parameter 2.
+    ///   - p3: Parameter 3.
+    /// - Returns: Never returns.
+    func documentedNeverReturns(p1: Int, p2: Int, p3: Int) -> Never {}
     """
     performLint(ValidateDocumentationComments.self, input: input)
     XCTAssertDiagnosed(.removeReturnComment(funcName: "noReturn"), line: 8, column: 1)
     XCTAssertDiagnosed(.documentReturnValue(funcName: "foo"), line: 16, column: 37)
+    XCTAssertNotDiagnosed(.documentReturnValue(funcName: "neverReturns"))
+    XCTAssertNotDiagnosed(.removeReturnComment(funcName: "documentedNeverReturns"))
   }
 
   func testValidDocumentation() {