Merge pull request swiftlang#948 from TTOzzi/allow-rethrows-docc-ValidateDocumentationComments

Make ValidateDocumentationComments allow `Throws` doc comments for rethrows functions

Author: allevato

Sources/SwiftFormat/Rules/ValidateDocumentationComments.swift

@@ -131,12 +131,13 @@ public final class ValidateDocumentationComments: SyntaxLintRule {
     throwsDescription: Paragraph?,
     node: DeclSyntax
   ) {
-    // If a function is marked as `rethrows`, it doesn't have any errors of its
-    // own that should be documented. So only require documentation for
-    // functions marked `throws`.
+    // Documentation is required for functions marked as `throws`.
+    // For functions marked as `rethrows`, documentation is not enforced
+    // since they don’t introduce new errors of their own.
+    // However, it can still be included if needed.
     let needsThrowsDesc = throwsOrRethrowsKeyword?.tokenKind == .keyword(.throws)
 
-    if !needsThrowsDesc && throwsDescription != nil {
+    if throwsOrRethrowsKeyword == nil && throwsDescription != nil {
       diagnose(
         .removeThrowsComment(funcName: name),
         on: throwsOrRethrowsKeyword ?? node.firstToken(viewMode: .sourceAccurate)

Tests/SwiftFormatTests/Rules/ValidateDocumentationCommentsTests.swift

@@ -95,7 +95,6 @@ final class ValidateDocumentationCommentsTests: LintOrFormatRuleTestCase {
       findings: [
         FindingSpec("1️⃣", message: "remove the 'Throws:' sections of 'doesNotThrow'; it does not throw any errors"),
         FindingSpec("2️⃣", message: "add a 'Throws:' section to document the errors thrown by 'doesThrow'"),
-        FindingSpec("3️⃣", message: "remove the 'Throws:' sections of 'doesRethrow'; it does not throw any errors"),
       ]
     )
   }