Merge pull request swiftlang#227 from dylansturg/more_optional_rules

Migrate some rules to opt-in status.

Author: allevato

Sources/SwiftFormatConfiguration/RuleRegistry+Generated.swift

@@ -32,7 +32,7 @@ enum RuleRegistry {
     "NoCasesWithOnlyFallthrough": true,
     "NoEmptyTrailingClosureParentheses": true,
     "NoLabelsInCasePatterns": true,
-    "NoLeadingUnderscores": true,
+    "NoLeadingUnderscores": false,
     "NoParensAroundConditions": true,
     "NoVoidReturnOnFunctionSignature": true,
     "OneCasePerLine": true,
@@ -45,6 +45,6 @@ enum RuleRegistry {
     "UseSingleLinePropertyGetter": true,
     "UseSynthesizedInitializer": true,
     "UseTripleSlashForDocumentationComments": true,
-    "ValidateDocumentationComments": true,
+    "ValidateDocumentationComments": false,
   ]
 }

Sources/SwiftFormatRules/NoLeadingUnderscores.swift

@@ -25,6 +25,12 @@ import SwiftSyntax
 /// Lint: Declaring an identifier with a leading underscore yields a lint error.
 public final class NoLeadingUnderscores: SyntaxLintRule {
 
+  /// Identifies this rule as being opt-in. While leading underscores aren't meant to be used in
+  /// normal circumstances, there are situations where they can be used to hint which APIs should be
+  /// avoided by general users. In particular when APIs must be exported publicly, but the author
+  /// doesn't intend for arbitrary usage.
+  public override class var isOptIn: Bool { return true }
+
   public override func visit(_ node: AssociatedtypeDeclSyntax) -> SyntaxVisitorContinueKind {
     diagnoseIfNameStartsWithUnderscore(node.identifier)
     return .visitChildren

Sources/SwiftFormatRules/ValidateDocumentationComments.swift

@@ -22,6 +22,11 @@ import SwiftSyntax
 ///       invalid (uses `Parameters` when there is only one parameter) will yield a lint error.
 public final class ValidateDocumentationComments: SyntaxLintRule {
 
+  /// Identifies this rule as being opt-in. Accurate and complete documentation comments are
+  /// important, but this rule isn't able to handle situations where portions of documentation are
+  /// redundant. For example when the returns clause is redundant for a simple declaration.
+  public override class var isOptIn: Bool { return true }
+
   public override func visit(_ node: InitializerDeclSyntax) -> SyntaxVisitorContinueKind {
     return checkFunctionLikeDocumentation(
       DeclSyntax(node), name: "init", parameters: node.parameters.parameterList, throwsOrRethrowsKeyword: node.throwsOrRethrowsKeyword)