Fix lint errors for missing documentation comments.

PiperOrigin-RevId: 194941919

Author: hbh

tools/swift-format/Sources/Configuration/Configuration.swift

@@ -3,52 +3,62 @@ public class Configuration: Codable {
   /// The version of the configuration; used in case of breaking changes in the future.
   public let version = 1
 
-  // MARK: Common configuration
+  /// MARK: Common configuration
 
   /// The maximum number of consecutive blank lines that may appear in a file.
   public let maximumBlankLines = 1
 
-  // The width of the horizontal tab in spaces.
-  // Used when converting indentation type.
+  /// The width of the horizontal tab in spaces.
+  /// Used when converting indentation type.
   public let tabWidth = 8
 
-  // A string that represents a single level of indentation.
-  // All indentation will be conducted in multiples of this string.
+  /// A string that represents a single level of indentation.
+  /// All indentation will be conducted in multiples of this string.
   public let indentation = "  "
 
-  // MARK: Rule-specific configuration
+  /// MARK: Rule-specific configuration
 
+  /// Rules for limiting blank lines between members.
   public let blankLineBetweenMembers = BlankLineBetweenMembersConfiguration()
 
+  /// Rules for adding backticks around special symbols in documentation comments.
   public let surroundSymbolsWithBackticks = SurroundSymbolsWithBackticksConfiguration()
 
   /// Constructs a Configuration with all default values.
   public init() {}
 }
 
+/// Configuration for the BlankLineBetweenMembers rule.
 public struct BlankLineBetweenMembersConfiguration: Codable {
-  // If true, blank lines are not required between single-line properties.
+  /// If true, blank lines are not required between single-line properties.
   public let ignoreSingleLineProperties = true
 }
 
 // TODO(abl): Expand the whitelist and blacklist.
+/// Configuration for the SurroundSymbolsWithBackticks rule.
 public struct SurroundSymbolsWithBackticksConfiguration: Codable {
-  // List of global symbols; added to the list of file-local symbols. Case-sensitive.
+  /// List of global symbols; added to the list of file-local symbols. Case-sensitive.
   public let symbolWhitelist = ["String"]
 
-  // List of symbols to ignore. Case-sensitive.
+  /// List of symbols to ignore. Case-sensitive.
   public let symbolBlacklist = [
-    "URL" // symbol name and capitalization is the same as the term.
+    "URL", // symbol name and capitalization is the same as the term.
   ]
 }
 
+/// Configuration for the NoPlaygroundLiterals rule.
 public struct NoPlaygroundLiteralsConfiguration: Codable {
   public enum ResolveBehavior: String, Codable {
-    case useUIColor // if not sure, use `UIColor` to replace `#colorLiteral`
-    case useNSColor // if not sure, use `NSColor` to replace `#colorLiteral`
-    case error // if not sure, raise an error
+    /// If not sure, use `UIColor` to replace `#colorLiteral`.
+    case useUIColor
+
+    /// If not sure, use `NSColor` to replace `#colorLiteral`.
+    case useNSColor
+
+    /// If not sure, raise an error.
+    case error
   }
 
-  // Resolution behavior to use when encountering an ambiguous `#colorLiteral`
+  /// Resolution behavior to use when encountering an ambiguous `#colorLiteral`.
   public let resolveAmbiguousColor: ResolveBehavior = .useUIColor
 }

tools/swift-format/Sources/Core/Context.swift

@@ -7,10 +7,16 @@ import SwiftSyntax
 /// Specifically, it is the container for the shared configuration, diagnostic engine, and URL of
 /// the current file.
 public class Context {
+  /// The configuration for this run of the pipeline, provided by a configuration JSON file.
   public let configuration: Configuration
+
+  /// The engine in which to emit diagnostics, if running in Lint mode.
   public let diagnosticEngine: DiagnosticEngine?
+
+  /// The URL of the file being linted or formatted.
   public let fileURL: URL
 
+  /// Creates a new Context with the provided configuration, diagnostic engine, and file URL.
   public init(configuration: Configuration, diagnosticEngine: DiagnosticEngine?, fileURL: URL) {
     self.configuration = configuration
     self.diagnosticEngine = diagnosticEngine

tools/swift-format/Sources/Core/FileRule.swift

@@ -1,9 +1,13 @@
 import Configuration
 import SwiftSyntax
 
+/// A linting rule that does not parse the file, but instead runs analyses over the raw text of
+/// the file.
 open class FileRule: Rule {
+  /// The context in which this rule in run.
   public let context: Context
 
+  /// Creates a new FileRule executing in the provided context.
   public required init(context: Context) {
     self.context = context
   }

tools/swift-format/Sources/Core/Rule.swift

@@ -1,12 +1,19 @@
+/// A Rule is a linting or formatting pass that executes in a given context.
 public protocol Rule {
+  /// The context in which the rule is executed.
   var context: Context { get }
+
+  /// The human-readable name of the rule. This defaults to the class name.
   var ruleName: String { get }
+
+  /// Creates a new Rule in a given context.
   init(context: Context)
 }
 
 private var nameCache = [ObjectIdentifier: String]()
 
 extension Rule {
+  /// By default, the `ruleName` is just the name of the implementing rule class.
   public var ruleName: String {
     let myType = type(of: self)
     // TODO(abl): Test and potentially replace with static initialization.

tools/swift-format/Sources/Core/SyntaxFormatRule.swift

@@ -1,8 +1,11 @@
 import SwiftSyntax
 
+/// A rule that both formats and lints a given file.
 open class SyntaxFormatRule: SyntaxRewriter, Rule {
+  /// The context in which the rule is executed.
   public let context: Context
 
+  /// Creates a new SyntaxFormatRule in the given context.
   public required init(context: Context) {
     self.context = context
   }

tools/swift-format/Sources/Core/SyntaxLintRule.swift

@@ -1,8 +1,11 @@
 import SwiftSyntax
 
+/// A rule that lints a given file.
 open class SyntaxLintRule: SyntaxVisitor, Rule {
+  /// The context in which the rule is executed.
   public let context: Context
 
+  /// Creates a new SyntaxLintRule in the given context.
   public required init(context: Context) {
     self.context = context
   }

tools/swift-format/Sources/generate-pipeline/main.swift

@@ -87,6 +87,7 @@ for baseName in fm.enumerator(atPath: rulesDir.path)! {
 }
 
 extension FileHandle: TextOutputStream {
+  /// Writes the provided string as data to a file output stream.
   public func write(_ string: String) {
     guard let data = string.data(using: .utf8) else { return }
     write(data)