Merge pull request swiftlang#172 from dylansturg/why_comments_so_broken

Restrict doc-block to doc-line transform to first doc comment.

Author: allevato

Sources/SwiftFormatRules/UseTripleSlashForDocumentationComments.swift

@@ -73,17 +73,23 @@ public final class UseTripleSlashForDocumentationComments: SyntaxFormatRule {
   /// a docLineComment.
   private func convertDocBlockCommentToDocLineComment(_ decl: DeclSyntax) -> DeclSyntax {
     guard let commentText = decl.docComment else { return decl }
-    guard let declLeadinTrivia = decl.leadingTrivia else { return decl }
+    guard let declLeadingTrivia = decl.leadingTrivia else { return decl }
     let docComments = commentText.components(separatedBy: "\n")
     var pieces = [TriviaPiece]()
 
     // Ensures the documentation comment is a docLineComment.
     var hasFoundDocComment = false
-    for piece in declLeadinTrivia.reversed() {
+    for piece in declLeadingTrivia.reversed() {
       if case .docBlockComment(_) = piece, !hasFoundDocComment {
         hasFoundDocComment = true
         diagnose(.avoidDocBlockComment, on: decl)
         pieces.append(contentsOf: separateDocBlockIntoPieces(docComments).reversed())
+      } else if case .docLineComment(_) = piece, !hasFoundDocComment {
+        // The comment was a doc-line comment all along. Leave it alone.
+        // This intentionally only considers the comment closest to the decl. There may be other
+        // comments, including block or doc-block comments, which are left as-is because they aren't
+        // necessarily related to the decl and are unlikely part of the decl's documentation.
+        return decl
       } else {
         pieces.append(piece)
       }

Tests/SwiftFormatRulesTests/UseTripleSlashForDocumentationCommentsTests.swift

@@ -54,4 +54,95 @@ final class UseTripleSlashForDocumentationCommentsTests: LintOrFormatRuleTestCas
                 public var test = 1
                 """)
   }
+
+  func testMultipleTypesOfDocComments() {
+    XCTAssertFormatting(
+      UseTripleSlashForDocumentationComments.self,
+      input: """
+             /**
+              * This is my preamble. It could be important.
+              * This comment stays as-is.
+              */
+
+             /// This decl has a comment.
+             /// The comment is multiple lines long.
+             public class AClazz {
+             }
+             """,
+      expected: """
+                /**
+                 * This is my preamble. It could be important.
+                 * This comment stays as-is.
+                 */
+
+                /// This decl has a comment.
+                /// The comment is multiple lines long.
+                public class AClazz {
+                }
+                """)
+  }
+
+  func testMultipleDocLineComments() {
+    XCTAssertFormatting(
+      UseTripleSlashForDocumentationComments.self,
+      input: """
+             /// This is my preamble. It could be important.
+             /// This comment stays as-is.
+             ///
+
+             /// This decl has a comment.
+             /// The comment is multiple lines long.
+             public class AClazz {
+             }
+             """,
+      expected: """
+                /// This is my preamble. It could be important.
+                /// This comment stays as-is.
+                ///
+
+                /// This decl has a comment.
+                /// The comment is multiple lines long.
+                public class AClazz {
+                }
+                """)
+  }
+
+  func testManyDocComments() {
+    XCTAssertFormatting(
+      UseTripleSlashForDocumentationComments.self,
+      input: """
+             /**
+              * This is my preamble. It could be important.
+              * This comment stays as-is.
+              */
+
+             /// This is a doc-line comment!
+
+             /** This is a fairly short doc-block comment. */
+
+             /// Why are there so many comments?
+             /// Who knows! But there are loads.
+
+             /** AClazz is a class with good name. */
+             public class AClazz {
+             }
+             """,
+      expected: """
+                /**
+                 * This is my preamble. It could be important.
+                 * This comment stays as-is.
+                 */
+
+                /// This is a doc-line comment!
+
+                /** This is a fairly short doc-block comment. */
+
+                /// Why are there so many comments?
+                /// Who knows! But there are loads.
+
+                /// AClazz is a class with good name.
+                public class AClazz {
+                }
+                """)
+  }
 }

Tests/SwiftFormatRulesTests/XCTestManifests.swift

@@ -369,6 +369,9 @@ extension UseTripleSlashForDocumentationCommentsTests {
     //   `swift test --generate-linuxmain`
     // to regenerate.
     static let __allTests__UseTripleSlashForDocumentationCommentsTests = [
+        ("testManyDocComments", testManyDocComments),
+        ("testMultipleDocLineComments", testMultipleDocLineComments),
+        ("testMultipleTypesOfDocComments", testMultipleTypesOfDocComments),
         ("testRemoveDocBlockComments", testRemoveDocBlockComments),
         ("testRemoveDocBlockCommentsWithoutStars", testRemoveDocBlockCommentsWithoutStars),
     ]