Implement use triple slash for documentation comments (swiftlang#71)

Author: atamez31

Diff for: Sources/Rules/DeclSyntax+Comments.swift

@@ -5,11 +5,11 @@ extension DeclSyntax {
   public var docComment: String? {
     guard let tok = firstToken else { return nil }
     var comment = [String]()
-
+    
     // We need to skip trivia until we see the first comment. This trivia will include all the
     // spaces and newlines before the doc comment.
     var hasSeenFirstLineComment = false
-
+    
     // Look through for discontiguous doc comments, separated by more than 1 newline.
     gatherComments: for piece in tok.leadingTrivia.reversed() {
       switch piece {
@@ -19,7 +19,32 @@ extension DeclSyntax {
         if hasSeenFirstLineComment {
           break gatherComments
         }
-        return text
+        let blockComment = text.components(separatedBy: "\n")
+        // Removes the marks of the block comment.
+        var isTheFirstLine = true
+        let blockCommentWithoutMarks = blockComment.map { (line: String) -> String in
+          // Only the first line of the block comment start with '/**'
+          let markToRemove = isTheFirstLine ? "/**" : "* "
+          let lineTrim = line.trimmingCharacters(in: .whitespaces)
+          if lineTrim.starts(with: markToRemove) {
+            let numCharsToRemove = isTheFirstLine ? markToRemove.count : markToRemove.count - 1
+            isTheFirstLine = false
+            return lineTrim.hasSuffix("*/") ?
+              String(lineTrim.dropFirst(numCharsToRemove).dropLast(3)) :
+              String(lineTrim.dropFirst(numCharsToRemove))
+          }
+          else if lineTrim == "*" {
+            return ""
+            
+          }
+          else if lineTrim.hasSuffix("*/") {
+            return String(line.dropLast(3))
+          }
+          isTheFirstLine = false
+          return line
+        }
+        
+        return blockCommentWithoutMarks.joined(separator: "\n").trimmingCharacters(in: .newlines)
       case .docLineComment(let text):
         // Mark that we've started grabbing sequential line comments and append it to the
         // comment buffer.
@@ -38,6 +63,9 @@ extension DeclSyntax {
         }
       }
     }
-    return comment.isEmpty ? nil : comment.joined(separator: "\n")
+    
+    /// Removes the "///" from every line of comment
+    let docLineComments = comment.reversed().map { $0.dropFirst(3) }
+    return comment.isEmpty ? nil : docLineComments.joined(separator: "\n")
   }
 }

Diff for: Sources/Rules/UseTripleSlashForDocumentationComments.swift

@@ -4,17 +4,115 @@ import SwiftSyntax
 
 /// Documentation comments must use the `///` form.
 ///
-/// Flag comments (e.g. `// TODO(username):`) are exempted from this rule.
+/// This is similar to `NoBlockComments` but is meant to prevent documentation block comments.
 ///
-/// This is similar to `NoBlockComments` but is meant to prevent multi-line comments that use `//`.
+/// Lint: If a doc block comment appears, a lint error is raised.
 ///
-/// Lint: If a declaration has a multi-line comment preceding it and that comment is not in `///`
-///       form, a lint error is raised.
-///
-/// Format: If a declaration has a multi-line comment preceding it and that comment is not in `///`
-///         form, it is converted to the `///` form.
+/// Format: If a doc block comment appears on its own on a line, or if a doc block comment spans multiple
+///         lines without appearing on the same line as code, it will be replaced with multiple
+///         doc line comments.
 ///
 /// - SeeAlso: https://google.github.io/swift#general-format
-public final class UseTripleSlashForDocumentationComments {
+public final class UseTripleSlashForDocumentationComments: SyntaxFormatRule {
+  public override func visit(_ node: FunctionDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: EnumDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: InitializerDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: DeinitializerDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: SubscriptDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: ClassDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: VariableDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: StructDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: ProtocolDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
 
+  public override func visit(_ node: TypealiasDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  public override func visit(_ node: ExtensionDeclSyntax) -> DeclSyntax {
+    return convertDocBlockCommentToDocLineComment(node)
+  }
+
+  /// In the case the given declaration has a docBlockComment as it's documentation
+  /// comment. Returns the declaration with the docBlockComment converted to
+  /// a docLineComment.
+  func convertDocBlockCommentToDocLineComment(_ decl: DeclSyntax) -> DeclSyntax {
+    guard let commentText = decl.docComment else { return decl }
+    guard let declLeadinTrivia = 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() {
+      if case .docBlockComment(_) = piece, !hasFoundDocComment {
+        hasFoundDocComment = true
+        diagnose(.avoidDocBlockComment, on: decl)
+        pieces.append(contentsOf: separateDocBlockIntoPieces(docComments).reversed())
+      }
+      else {
+        pieces.append(piece)
+      }
+    }
+
+    return !hasFoundDocComment ? decl  :
+      replaceTrivia(
+      on: decl,
+      token: decl.firstToken,
+      leadingTrivia: Trivia(pieces: pieces.reversed())
+      ) as! DeclSyntax
+  }
+
+  /// Breaks down the docBlock comment into the correct trivia pieces
+  /// for a docLineComment.
+  func separateDocBlockIntoPieces(_ docComments: [String]) -> [TriviaPiece]
+  {
+    var pieces = [TriviaPiece]()
+    for lineText in docComments.dropLast() {
+      // Adds an space as indentation for the lines that needed it.
+      let docLineMark = lineText.first == " " ||
+        lineText.trimmingCharacters(in: .whitespaces) == "" ? "///" : "/// "
+      pieces.append(.docLineComment(docLineMark + lineText))
+      pieces.append(.newlines(1))
+    }
+
+    // The last piece doesn't need a newline after it.
+    if docComments.last!.trimmingCharacters(in: .whitespaces) != "" {
+      let docLineMark = docComments.last!.first == " " ||
+        docComments.last!.trimmingCharacters(in: .whitespaces) == "" ? "///" : "/// "
+      pieces.append(.docLineComment(docLineMark + docComments.last!))
+    }
+    return pieces
+  }
+}
+
+extension Diagnostic.Message {
+  static let avoidDocBlockComment =
+    Diagnostic.Message(.warning, "Documentation block comments are not allowed")
 }
+

Diff for: Tests/SwiftFormatTests/UseTripleSlashForDocumentationCommentsTests.swift

@@ -0,0 +1,67 @@
+import SwiftSyntax
+import XCTest
+
+@testable import Rules
+
+public class UseTripleSlashForDocumentationCommentsTests: DiagnosingTestCase {
+  public func testRemoveDocBlockComments() {
+    XCTAssertFormatting(
+      UseTripleSlashForDocumentationComments.self,
+      input: """
+             /**
+              * This comment should not be converted.
+              */
+             
+             /**
+              * Returns a docLineComment.
+              *
+              * - Parameters:
+              *   - withOutStar: Indicates if the comment start with a star.
+              * - Returns: docLineComment.
+              */
+             func foo(withOutStar: Bool) {}
+             """,
+      expected: """
+                /**
+                 * This comment should not be converted.
+                 */
+                
+                /// Returns a docLineComment.
+                ///
+                /// - Parameters:
+                ///   - withOutStar: Indicates if the comment start with a star.
+                /// - Returns: docLineComment.
+                func foo(withOutStar: Bool) {}
+                """)
+  }
+  
+  public func testRemoveDocBlockCommentsWithoutStars() {
+    XCTAssertFormatting(
+      UseTripleSlashForDocumentationComments.self,
+      input: """
+             /**
+              Returns a docLineComment.
+             
+              - Parameters:
+                - withStar: Indicates if the comment start with a star.
+              - Returns: docLineComment.
+              */
+             public var test = 1
+             """,
+      expected: """
+                /// Returns a docLineComment.
+                ///
+                /// - Parameters:
+                ///   - withStar: Indicates if the comment start with a star.
+                /// - Returns: docLineComment.
+                public var test = 1
+                """)
+  }
+  
+  #if !os(macOS)
+  static let allTests = [
+    UseTripleSlashForDocumentationCommentsTests.testRemoveDocBlockComments,
+    UseTripleSlashForDocumentationCommentsTeststestRemoveDocBlockCommentsWithoutStars,
+    ]
+  #endif
+}