Improvements to auto-generated rule docs

- Using `DocumentationCommentText` via `@_spi(Rules)` instead of our own
  implementation of rule description extracted from trivia.
- Added table of contents with all the available rules linked to their
  respective blocks.

Author: natikgadzhi

Documentation/RuleDocumentation.md

@@ -9,6 +9,47 @@ configuration file, as described in
 applied in the linter, but only some of them can format your source code
 automatically.
 
+Here's the list of available rules:
+
+- [AllPublicDeclarationsHaveDocumentation](#AllPublicDeclarationsHaveDocumentation)
+- [AlwaysUseLowerCamelCase](#AlwaysUseLowerCamelCase)
+- [AmbiguousTrailingClosureOverload](#AmbiguousTrailingClosureOverload)
+- [BeginDocumentationCommentWithOneLineSummary](#BeginDocumentationCommentWithOneLineSummary)
+- [DoNotUseSemicolons](#DoNotUseSemicolons)
+- [DontRepeatTypeInStaticProperties](#DontRepeatTypeInStaticProperties)
+- [FileScopedDeclarationPrivacy](#FileScopedDeclarationPrivacy)
+- [FullyIndirectEnum](#FullyIndirectEnum)
+- [GroupNumericLiterals](#GroupNumericLiterals)
+- [IdentifiersMustBeASCII](#IdentifiersMustBeASCII)
+- [NeverForceUnwrap](#NeverForceUnwrap)
+- [NeverUseForceTry](#NeverUseForceTry)
+- [NeverUseImplicitlyUnwrappedOptionals](#NeverUseImplicitlyUnwrappedOptionals)
+- [NoAccessLevelOnExtensionDeclaration](#NoAccessLevelOnExtensionDeclaration)
+- [NoAssignmentInExpressions](#NoAssignmentInExpressions)
+- [NoBlockComments](#NoBlockComments)
+- [NoCasesWithOnlyFallthrough](#NoCasesWithOnlyFallthrough)
+- [NoEmptyTrailingClosureParentheses](#NoEmptyTrailingClosureParentheses)
+- [NoLabelsInCasePatterns](#NoLabelsInCasePatterns)
+- [NoLeadingUnderscores](#NoLeadingUnderscores)
+- [NoParensAroundConditions](#NoParensAroundConditions)
+- [NoPlaygroundLiterals](#NoPlaygroundLiterals)
+- [NoVoidReturnOnFunctionSignature](#NoVoidReturnOnFunctionSignature)
+- [OmitExplicitReturns](#OmitExplicitReturns)
+- [OneCasePerLine](#OneCasePerLine)
+- [OneVariableDeclarationPerLine](#OneVariableDeclarationPerLine)
+- [OnlyOneTrailingClosureArgument](#OnlyOneTrailingClosureArgument)
+- [OrderedImports](#OrderedImports)
+- [ReplaceForEachWithForLoop](#ReplaceForEachWithForLoop)
+- [ReturnVoidInsteadOfEmptyTuple](#ReturnVoidInsteadOfEmptyTuple)
+- [TypeNamesShouldBeCapitalized](#TypeNamesShouldBeCapitalized)
+- [UseEarlyExits](#UseEarlyExits)
+- [UseLetInEveryBoundCaseVariable](#UseLetInEveryBoundCaseVariable)
+- [UseShorthandTypeNames](#UseShorthandTypeNames)
+- [UseSingleLinePropertyGetter](#UseSingleLinePropertyGetter)
+- [UseSynthesizedInitializer](#UseSynthesizedInitializer)
+- [UseTripleSlashForDocumentationComments](#UseTripleSlashForDocumentationComments)
+- [UseWhereClausesInForLoops](#UseWhereClausesInForLoops)
+- [ValidateDocumentationComments](#ValidateDocumentationComments)
 
 ### AllPublicDeclarationsHaveDocumentation
 
@@ -261,6 +302,15 @@ Format: Parentheses around such expressions are removed, if they do not cause a
 
 `NoParensAroundConditions` rule can format your code automatically.
 
+### NoPlaygroundLiterals
+
+The playground literals (`#colorLiteral`, `#fileLiteral`, and `#imageLiteral`) are forbidden.
+
+Lint: Using a playground literal will yield a lint error with a suggestion of an API to replace
+it.
+
+`NoPlaygroundLiterals` is a linter-only rule.
+
 ### NoVoidReturnOnFunctionSignature
 
 Functions that return `()` or `Void` should omit the return signature.

Sources/SwiftFormat/Core/DocumentationCommentText.swift

@@ -18,6 +18,7 @@ import SwiftSyntax
 /// structural organization. It automatically handles trimming leading indentation from comments as
 /// well as "ASCII art" in block comments (i.e., leading asterisks on each line).
 @_spi(Testing)
+@_spi(Rules)
 public struct DocumentationCommentText {
   /// Denotes the kind of punctuation used to introduce the comment.
   public enum Introducer {

Sources/generate-pipeline/RuleCollector.swift

@@ -20,14 +20,13 @@ import SwiftParser
 final class RuleCollector {
   /// Information about a detected rule.
   struct DetectedRule: Hashable {
-
-    /// The DocC comments of the rule,
-    /// extracted from the .leadingTrivia of the rule class or struct.
-    let doccComment: String
-
     /// The type name of the rule.
     let typeName: String
 
+    /// The description of the rule, extracted from the rule class or struct DocC comment
+    /// with `DocumentationCommentText(extractedFrom:)`
+    let description: String?
+
     /// The syntax node types visited by the rule type.
     let visitedNodes: [String]
 
@@ -91,15 +90,13 @@ final class RuleCollector {
     let typeName: String
     let members: MemberBlockItemListSyntax
     let maybeInheritanceClause: InheritanceClauseSyntax?
-    let doccComment: String
+    let description = DocumentationCommentText(extractedFrom: statement.item.leadingTrivia)
 
     if let classDecl = statement.item.as(ClassDeclSyntax.self) {
-      doccComment = classDecl.leadingTrivia.description
       typeName = classDecl.name.text
       members = classDecl.memberBlock.members
       maybeInheritanceClause = classDecl.inheritanceClause
     } else if let structDecl = statement.item.as(StructDeclSyntax.self) {
-      doccComment = structDecl.leadingTrivia.description
       typeName = structDecl.name.text
       members = structDecl.memberBlock.members
       maybeInheritanceClause = structDecl.inheritanceClause
@@ -148,8 +145,8 @@ final class RuleCollector {
         preconditionFailure("Failed to find type for rule named \(typeName)")
       }
       return DetectedRule(
-        doccComment: doccComment,
         typeName: typeName,
+        description: description?.text,
         visitedNodes: visitedNodes,
         canFormat: canFormat,
         isOptIn: ruleType.isOptIn)

Sources/generate-pipeline/RuleDocumentationGenerator.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 import Foundation
+import SwiftFormat
 
 /// Generates the markdown file with extended documenation on the available rules.
 final class RuleDocumentationGenerator: FileGenerator {
@@ -37,17 +38,25 @@ final class RuleDocumentationGenerator: FileGenerator {
       applied in the linter, but only some of them can format your source code
       automatically.
 
+      Here's the list of available rules:
+
 
       """
     )
 
     for detectedRule in ruleCollector.allLinters.sorted(by: { $0.typeName < $1.typeName }) {
       handle.write("""
+      - [\(detectedRule.typeName)](#\(detectedRule.typeName))
 
-      ### \(detectedRule.typeName)
+      """)
+    }
+
+    for detectedRule in ruleCollector.allLinters.sorted(by: { $0.typeName < $1.typeName }) {
+      handle.write("""
 
-      \(ruleDescription(for: detectedRule))
+      ### \(detectedRule.typeName)
 
+      \(detectedRule.description ?? "")
       \(ruleFormatSupportDescription(for: detectedRule))
 
       """)
@@ -59,25 +68,4 @@ final class RuleDocumentationGenerator: FileGenerator {
       "`\(rule.typeName)` rule can format your code automatically." :
       "`\(rule.typeName)` is a linter-only rule."
   }
-
-  /// Takes the DocC comment of the rule and strip `///` from the beginning of each line.
-  /// Also removes empty lines with under 4 characters.
-  private func ruleDescription(for rule: RuleCollector.DetectedRule) -> String {
-    let described = rule.doccComment.split(whereSeparator: \.isNewline)
-      .compactMap { line in
-        // Remove the first 4 characters, i.e. `/// `
-        if line.count >= 4 {
-          let index = line.index(line.startIndex, offsetBy: 4)
-          return line.suffix(from: index)
-        } else {
-          // For lines that have less than 4 characters, emit an empty line.
-          return ""
-        }
-      }
-      // not great, but that shoves multiple lines into the single
-      // table cell in markdown
-      .joined(separator: "\n")
-
-    return described
-  }
 }