Add more documentation comments (#4942)

In preparation for these declarations to become public.

Source/SwiftLintFramework/Models/Command.swift

@@ -45,12 +45,17 @@ public struct Command: Equatable {
         action != .invalid && modifier != .invalid && !ruleIdentifiers.isEmpty
     }
 
+    /// The action (verb) that SwiftLint should perform when interpreting this command.
     internal let action: Action
+    /// The identifiers for the rules associated with this command.
     internal let ruleIdentifiers: Set<RuleIdentifier>
+    /// The line in the source file where this command is defined.
     internal let line: Int
+    /// The character offset within the line in the source file where this command is defined.
     internal let character: Int?
+    /// This command's modifier, if any.
     internal let modifier: Modifier?
-    /// Currently unused but parsed separate from rule identifiers
+    /// The comment following this command's `-` delimiter, if any.
     internal let trailingComment: String?
 
     /// Creates a command based on the specified parameters.

Source/SwiftLintFramework/Protocols/CacheDescriptionProvider.swift

@@ -1,3 +1,6 @@
+/// Interface providing access to a cache description.
 internal protocol CacheDescriptionProvider {
+    /// The cache description which will be used to determine if a previous
+    /// cached value is still valid given the new cache value.
     var cacheDescription: String { get }
 }

Source/SwiftLintFramework/Rules/RuleConfigurations/RegexConfiguration.swift

@@ -1,15 +1,25 @@
 import Foundation
 import SourceKittenFramework
 
+/// A rule configuration used for defining custom rules in yaml.
 public struct RegexConfiguration: SeverityBasedRuleConfiguration, Hashable, CacheDescriptionProvider {
+    /// The identifier for this custom rule.
     public let identifier: String
+    /// The name for this custom rule.
     public var name: String?
+    /// The message to be presented when producing violations.
     public var message = "Regex matched"
+    /// The regular expression to apply to trigger violations for this custom rule.
     public var regex: NSRegularExpression!
+    /// Regular expressions to include when matching the file path.
     public var included: [NSRegularExpression] = []
+    /// Regular expressions to exclude when matching the file path.
     public var excluded: [NSRegularExpression] = []
+    /// The syntax kinds to exclude from matches. If the regex matched syntax kinds from this list, it would
+    /// be ignored and not count as a rule violation.
     public var excludedMatchKinds = Set<SyntaxKind>()
     public var severityConfiguration = SeverityConfiguration(.warning)
+    /// The index of the regex capture group to match.
     public var captureGroup: Int = 0
 
     public var consoleDescription: String {
@@ -35,11 +45,15 @@ public struct RegexConfiguration: SeverityBasedRuleConfiguration, Hashable, Cach
         queuedFatalError("Could not serialize regex configuration for cache")
     }
 
+    /// The `RuleDescription` for the custom rule defined here.
     public var description: RuleDescription {
         return RuleDescription(identifier: identifier, name: name ?? identifier,
                                description: "", kind: .style)
     }
 
+    /// Create a `RegexConfiguration` with the specified identifier, with other properties to be set later.
+    ///
+    /// - parameter identifier: The rule identifier to use.
     public init(identifier: String) {
         self.identifier = identifier
     }

Source/SwiftLintFramework/Rules/RuleConfigurations/SeverityConfiguration.swift

@@ -1,3 +1,4 @@
+/// A rule configuration that allows specifying the desired severity level for violations.
 public struct SeverityConfiguration: SeverityBasedRuleConfiguration, Equatable {
     public var consoleDescription: String {
         return severity.rawValue
@@ -9,6 +10,9 @@ public struct SeverityConfiguration: SeverityBasedRuleConfiguration, Equatable {
         self
     }
 
+    /// Create a `SeverityConfiguration` with the specified severity.
+    ///
+    /// - parameter severity: The severity that should be used when emitting violations.
     public init(_ severity: ViolationSeverity) {
         self.severity = severity
     }
@@ -17,13 +21,9 @@ public struct SeverityConfiguration: SeverityBasedRuleConfiguration, Equatable {
         let configString = configuration as? String
         let configDict = configuration as? [String: Any]
         guard let severityString: String = configString ?? configDict?["severity"] as? String,
-            let severity = severity(fromString: severityString) else {
+            let severity = ViolationSeverity(rawValue: severityString.lowercased()) else {
             throw ConfigurationError.unknownConfiguration
         }
         self.severity = severity
     }
-
-    private func severity(fromString string: String) -> ViolationSeverity? {
-        return ViolationSeverity(rawValue: string.lowercased())
-    }
 }

Source/SwiftLintFramework/Rules/RuleConfigurations/SeverityLevelsConfiguration.swift

@@ -1,3 +1,4 @@
+/// A rule configuration that allows specifying thresholds for `warning` and `error` severities.
 public struct SeverityLevelsConfiguration: RuleConfiguration, Equatable {
     public var consoleDescription: String {
         let errorString: String
@@ -9,6 +10,7 @@ public struct SeverityLevelsConfiguration: RuleConfiguration, Equatable {
         return "warning: \(warning)" + errorString
     }
 
+    /// A condensed console description.
     public var shortConsoleDescription: String {
         if let errorValue = error {
             return "w/e: \(warning)/\(errorValue)"
@@ -16,9 +18,21 @@ public struct SeverityLevelsConfiguration: RuleConfiguration, Equatable {
         return "w: \(warning)"
     }
 
+    /// The threshold for a violation to be a warning.
     var warning: Int
+    /// The threshold for a violation to be an error.
     var error: Int?
 
+    /// Create a `SeverityLevelsConfiguration` based on the sepecified `warning` and `error` thresholds.
+    ///
+    /// - parameter warning: The threshold for a violation to be a warning.
+    /// - parameter error:   The threshold for a violation to be an error.
+    init(warning: Int, error: Int? = nil) {
+        self.warning = warning
+        self.error = error
+    }
+
+    /// The rule parameters that define the thresholds that should map to each severity.
     var params: [RuleParameter<Int>] {
         if let error {
             return [RuleParameter(severity: .error, value: error),