Comment style

.swiftlint.yml

@@ -71,6 +71,8 @@ file_name:
  - GeneratedTests.swift
  - SwiftSyntax+SwiftLint.swift
  - TestHelpers.swift
+comment_style:
+ comment_style: mixed
 
 balanced_xctest_lifecycle: &unit_test_configuration
  test_parent_classes:

CHANGELOG.md

@@ -33,6 +33,11 @@
  [keith](https://github.com/keith)
  [5139](https://github.com/realm/SwiftLint/pull/5139)
 
+* Add `comment_style` rules to allow specifying whether a project should have a
+ specific comment style, between multiline and single line comments. 
+ [Michael Redig](https://github.com/mredig)
+ [PR 5148](https://github.com/realm/SwiftLint/pull/5148)
+
 #### Bug Fixes
 
 * Fix false positive in `control_statement` rule that triggered on conditions

Source/SwiftLintBuiltInRules/Models/BuiltInRules.swift

@@ -24,6 +24,7 @@ public let builtInRules: [Rule.Type] = [
  CommaInheritanceRule.self,
  CommaRule.self,
  CommentSpacingRule.self,
+ CommentStyleRule.self,
  CompilerProtocolInitRule.self,
  ComputedAccessorsOrderRule.self,
  ConditionalReturnsOnNewlineRule.self,

Source/SwiftLintBuiltInRules/Rules/RuleConfigurations/CommentStyleConfiguration.swift

@@ -0,0 +1,55 @@
+import Foundation
+import SwiftLintCore
+
+struct CommentStyleConfiguration: RuleConfiguration, Equatable {
+ typealias Parent = CommentStyleRule
+
+ /// Set this value to enforce a comment style for the entire project. If unset, each file will be evaluated
+ /// individually and enforce consistency with whatever style appears first within the file.
+ @ConfigurationElement(key: "comment_style")
+ private(set) var commentStyle: Style?
+ /// The number of single line comments allowed before requiring a multiline comment.
+ /// Only valid when `comment_style` is set to `mixed`
+ @ConfigurationElement(key: "line_comment_threshold")
+ private(set) var lineCommentThreshold: Int?
+ @ConfigurationElement(key: "severity")
+ private(set) var severityConfiguration = SeverityConfiguration<Parent>(.warning)
+
+ mutating func apply(configuration: Any) throws {
+ guard
+ let configurationDict = configuration as? [String: Any]
+ else { throw Issue.unknownConfiguration(ruleID: Parent.identifier) }
+
+ if let commentStyleString: String = configurationDict[key: $commentStyle] {
+ let style = Style(rawValue: commentStyleString)
+ style != nil ? () : print("'\(commentStyleString)' invalid for comment style. No style enforce.")
+ self.commentStyle = style
+ }
+
+ if
+ commentStyle == .mixed,
+ let lineCommentThreshold: Int = configurationDict[key: $lineCommentThreshold] {
+ self.lineCommentThreshold = lineCommentThreshold
+ }
+
+ if let severityString: String = configurationDict[key: $severityConfiguration] {
+ try severityConfiguration.apply(configuration: severityString)
+ }
+ }
+}
+
+extension CommentStyleConfiguration {
+ enum Style: String, AcceptableByConfigurationElement {
+ case multiline
+ case singleline
+ case mixed
+
+ func asOption() -> SwiftLintCore.OptionType { .string(rawValue) }
+ }
+}
+
+extension Dictionary where Key == String, Value == Any {
+ subscript<T>(key key: String) -> T? {
+ self[key] as? T
+ }
+}

Source/SwiftLintBuiltInRules/Rules/Style/CommentStyleRule.swift

@@ -0,0 +1,221 @@
+import Foundation
+import SwiftIDEUtils
+import SwiftSyntax
+
+struct CommentStyleRule: SwiftSyntaxRule, OptInRule, ConfigurationProviderRule {
+ typealias ConfigurationType = CommentStyleConfiguration
+
+ var configuration = ConfigurationType()
+
+ static let description = RuleDescription(
+ identifier: "comment_style",
+ name: "Comment Style",
+ description: """
+ Allows for options to enforce styling of comments. Should all comments be multiline comments? Should they be single
+ line? Or should there be a threshold, where if x number of single line comments are in a row, should they be
+ multiline?
+ """,
+ kind: .style,
+ minSwiftVersion: .current,
+ nonTriggeringExamples: CommentStyleRuleExamples.generateNonTriggeringExamples(),
+ triggeringExamples: CommentStyleRuleExamples.generateTriggeringExamples())
+
+ func makeVisitor(file: SwiftLintFile) -> ViolationsSyntaxVisitor {
+ Visitor(configuration: configuration, file: file)
+ }
+}
+
+extension CommentStyleRule {
+ class Visitor: ViolationsSyntaxVisitor {
+ typealias Parent = CommentStyleRule // swiftlint:disable:this nesting
+
+ private let allCommentGroupings: [CommentGrouping]
+ let file: SwiftLintFile
+
+ let configuration: Parent.ConfigurationType
+
+ typealias Style = Parent.ConfigurationType.Style // swiftlint:disable:this nesting
+ private var commentStyle: Style?
+
+ enum CommentGrouping { // swiftlint:disable:this nesting
+ case singleline([SyntaxClassifiedRange])
+ case multiline([SyntaxClassifiedRange])
+ case singlelineDoc([SyntaxClassifiedRange])
+ case multilineDoc([SyntaxClassifiedRange])
+ }
+
+ init(configuration: Parent.ConfigurationType, file: SwiftLintFile) {
+ self.configuration = configuration
+ self.file = file
+
+ var rangeGroupings: [CommentGrouping] = []
+ var commentsAccumulator: [SyntaxClassifiedRange] = []
+
+ func appendCommentsAccumulator() {
+ guard commentsAccumulator.isEmpty == false else { return }
+
+ guard
+ let kind = commentsAccumulator.first?.kind,
+ commentsAccumulator.allSatisfy({ $0.kind == kind })
+ else { queuedFatalError("Accumulator acquired mixed comment kind...") }
+
+ switch kind {
+ case .lineComment:
+ rangeGroupings.append(.singleline(commentsAccumulator))
+ case .blockComment:
+ rangeGroupings.append(.multiline(commentsAccumulator))
+ case .docLineComment:
+ rangeGroupings.append(.singlelineDoc(commentsAccumulator))
+ case .docBlockComment:
+ rangeGroupings.append(.multilineDoc(commentsAccumulator))
+ default:
+ queuedFatalError("non comment in comment accumulator")
+ }
+ commentsAccumulator.removeAll()
+ }
+
+ let commandLines = file.commands.reduce(into: Set<Int>()) { commandLines, command in
+ commandLines.insert(command.line)
+ }
+
+ let fileData = Data(file.contents.utf8)
+ for classificationRange in file.syntaxClassifications {
+ let location = file.locationConverter.location(for: AbsolutePosition(utf8Offset: classificationRange.offset))
+ guard commandLines.contains(location.line) == false else { continue }
+
+ switch classificationRange.kind {
+ case _ where classificationRange.kind.isComment == true:
+ if commentsAccumulator.last?.kind != classificationRange.kind {
+ appendCommentsAccumulator()
+ }
+ commentsAccumulator.append(classificationRange)
+ case .none:
+ if
+ let text = Self.convertToString(from: classificationRange, withOriginalStringData: fileData),
+ text.countOccurrences(of: "\n") > 1 {
+ appendCommentsAccumulator()
+ }
+ default:
+ appendCommentsAccumulator()
+ }
+ }
+ appendCommentsAccumulator()
+
+ self.allCommentGroupings = rangeGroupings
+ self.commentStyle = configuration.commentStyle
+ super.init(viewMode: .sourceAccurate)
+ }
+
+ override func visitPost(_ node: SourceFileSyntax) {
+ for grouping in allCommentGroupings {
+ switch grouping {
+ case .singleline(let commentGroup):
+ visitPostComment(commentGroup)
+ case .multiline(let commentGroup):
+ visitPostBlockComment(commentGroup)
+ case .singlelineDoc(let commentGroup):
+ visitPostDocComment(commentGroup)
+ case .multilineDoc(let commentGroup):
+ visitPostBlockDockComment(commentGroup)
+ }
+ }
+ }
+
+ func visitPostComment(_ commentRangeGroup: [SyntaxClassifiedRange]) {
+ guard let firstCommentInGroup = commentRangeGroup.first else { return }
+ if case .fail(let reason, let severity) = validateCommentStyle(.singleline) {
+ appendViolation(
+ at: AbsolutePosition(utf8Offset: firstCommentInGroup.offset),
+ reason: reason,
+ severity: severity)
+ return
+ }
+
+ if case .fail(let reason, let severity) = validateSinglelineCommentLineLength(commentRangeGroup.count) {
+ appendViolation(
+ at: AbsolutePosition(utf8Offset: firstCommentInGroup.offset),
+ reason: reason,
+ severity: severity)
+ return
+ }
+ }
+
+ func visitPostBlockComment(_ commentRangeGroup: [SyntaxClassifiedRange]) {
+ guard let firstCommentInGroup = commentRangeGroup.first else { return }
+ if case .fail(let reason, let severity) = validateCommentStyle(.multiline) {
+ appendViolation(
+ at: AbsolutePosition(utf8Offset: firstCommentInGroup.offset),
+ reason: reason,
+ severity: severity)
+ return
+ }
+ }
+
+ func visitPostDocComment(_ commentRangeGroup: [SyntaxClassifiedRange]) {}
+
+ func visitPostBlockDockComment(_ commentRangeGroup: [SyntaxClassifiedRange]) {}
+
+ private func validateCommentStyle(_ style: Style) -> Validation {
+ let commentStyle = self.commentStyle ?? style
+ self.commentStyle = commentStyle
+
+ switch commentStyle {
+ case .mixed:
+ return .pass
+ default:
+ guard style == commentStyle else {
+ return .fail(
+ reason: "\(style.rawValue.capitalized) comments not allowed",
+ severity: configuration.severityConfiguration.severity)
+ }
+ return .pass
+ }
+ }
+
+ private func validateSinglelineCommentLineLength(_ lineLength: Int) -> Validation {
+ guard
+ commentStyle == .mixed,
+ let threshold = configuration.lineCommentThreshold
+ else { return .pass }
+
+ if lineLength < threshold {
+ return .pass
+ } else {
+ return .fail(
+ reason: "Block comments required for comments spanning \(threshold) or more lines",
+ severity: configuration.severityConfiguration.severity)
+ }
+ }
+
+ private static func convertToString(
+ from range: SyntaxClassifiedRange,
+ withOriginalStringData originalStringData: Data) -> String? {
+ let content = originalStringData[range.range.dataRange]
+ return String(data: content, encoding: .utf8)
+ }
+
+ @discardableResult
+ private func appendViolation(
+ at position: AbsolutePosition,
+ reason: String,
+ severity: ViolationSeverity) -> ReasonedRuleViolation {
+ let violation = ReasonedRuleViolation(
+ position: position,
+ reason: reason,
+ severity: severity)
+ violations.append(violation)
+ return violation
+ }
+
+ enum Validation { // swiftlint:disable:this nesting
+ case pass
+ case fail(reason: String, severity: ViolationSeverity)
+ }
+ }
+}
+
+private extension ByteSourceRange {
+ var dataRange: Range<Int> {
+ offset..<endOffset
+ }
+}