Update messaging for SA1027 to match new behavior

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/SpacingRules/SA1027CodeFixProvider.cs

@@ -18,15 +18,15 @@ namespace StyleCop.Analyzers.SpacingRules
     using Settings.ObjectModel;
 
     /// <summary>
-    /// Implements a code fix for <see cref="SA1027TabsMustNotBeUsed"/>.
+    /// Implements a code fix for <see cref="SA1027UseTabsCorrectly"/>.
     /// </summary>
     [ExportCodeFixProvider(LanguageNames.CSharp, Name = nameof(SA1027CodeFixProvider))]
     [Shared]
     internal class SA1027CodeFixProvider : CodeFixProvider
     {
         /// <inheritdoc/>
         public override ImmutableArray<string> FixableDiagnosticIds { get; } =
-            ImmutableArray.Create(SA1027TabsMustNotBeUsed.DiagnosticId);
+            ImmutableArray.Create(SA1027UseTabsCorrectly.DiagnosticId);
 
         /// <inheritdoc/>
         public override FixAllProvider GetFixAllProvider()
@@ -65,9 +65,9 @@ private static TextChange FixDiagnostic(IndentationSettings indentationSettings,
 
             bool useTabs = false;
             string behavior;
-            if (diagnostic.Properties.TryGetValue(SA1027TabsMustNotBeUsed.BehaviorKey, out behavior))
+            if (diagnostic.Properties.TryGetValue(SA1027UseTabsCorrectly.BehaviorKey, out behavior))
             {
-                useTabs = behavior == SA1027TabsMustNotBeUsed.ConvertToTabsBehavior;
+                useTabs = behavior == SA1027UseTabsCorrectly.ConvertToTabsBehavior;
             }
 
             string text = sourceText.ToString(TextSpan.FromBounds(startLine.Start, span.End));

StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1027UnitTests.cs

@@ -13,7 +13,7 @@ namespace StyleCop.Analyzers.Test.SpacingRules
     using Xunit;
 
     /// <summary>
-    /// Unit tests for <see cref="SA1027TabsMustNotBeUsed"/>
+    /// Unit tests for <see cref="SA1027UseTabsCorrectly"/>
     /// </summary>
     public class SA1027UnitTests : CodeFixVerifier
     {
@@ -237,7 +237,7 @@ Comment 2
         /// <inheritdoc/>
         protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
         {
-            yield return new SA1027TabsMustNotBeUsed();
+            yield return new SA1027UseTabsCorrectly();
         }
 
         /// <inheritdoc/>

StyleCop.Analyzers/StyleCop.Analyzers.Test/SpacingRules/SA1027UseTabsUnitTests.cs

@@ -14,7 +14,7 @@ namespace StyleCop.Analyzers.Test.SpacingRules
     using Xunit;
 
     /// <summary>
-    /// Unit tests for <see cref="SA1027TabsMustNotBeUsed"/> when <see cref="IndentationSettings.UseTabs"/> is
+    /// Unit tests for <see cref="SA1027UseTabsCorrectly"/> when <see cref="IndentationSettings.UseTabs"/> is
     /// <see langword="true"/>.
     /// </summary>
     public class SA1027UseTabsUnitTests : CodeFixVerifier
@@ -251,7 +251,7 @@ protected override string GetSettings() =>
         /// <inheritdoc/>
         protected override IEnumerable<DiagnosticAnalyzer> GetCSharpDiagnosticAnalyzers()
         {
-            yield return new SA1027TabsMustNotBeUsed();
+            yield return new SA1027UseTabsCorrectly();
         }
 
         /// <inheritdoc/>

…/SpacingRules/SA1027TabsMustNotBeUsed.cs …s/SpacingRules/SA1027UseTabsCorrectly.csStyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1027TabsMustNotBeUsed.cs renamed to StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1027UseTabsCorrectly.cs StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1027TabsMustNotBeUsed.cs renamed to StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SA1027UseTabsCorrectly.cs

@@ -12,23 +12,13 @@ namespace StyleCop.Analyzers.SpacingRules
     using StyleCop.Analyzers.Settings.ObjectModel;
 
     /// <summary>
-    /// The C# code contains a tab character.
+    /// The code contains a tab or space character which is not consistent with the current project settings.
     /// </summary>
-    /// <remarks>
-    /// <para>A violation of this rule occurs whenever the code contains a tab character.</para>
-    ///
-    /// <para>Tabs should not be used within C# code, because the length of the tab character can vary depending upon
-    /// the editor being used to view the code. This can cause the spacing and indexing of the code to vary from the
-    /// developer's original intention, and can in some cases make the code difficult to read.</para>
-    ///
-    /// <para>For these reasons, tabs should not be used, and each level of indentation should consist of four spaces.
-    /// This will ensure that the code looks the same no matter which editor is being used to view the code.</para>
-    /// </remarks>
     [DiagnosticAnalyzer(LanguageNames.CSharp)]
-    internal class SA1027TabsMustNotBeUsed : DiagnosticAnalyzer
+    internal class SA1027UseTabsCorrectly : DiagnosticAnalyzer
     {
         /// <summary>
-        /// The ID for diagnostics produced by the <see cref="SA1027TabsMustNotBeUsed"/> analyzer.
+        /// The ID for diagnostics produced by the <see cref="SA1027UseTabsCorrectly"/> analyzer.
         /// </summary>
         public const string DiagnosticId = "SA1027";
 

StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SpacingResources.Designer.cs

@@ -220,13 +220,13 @@
     <value>Replace tabs with spaces</value>
   </data>
   <data name="SA1027Description" xml:space="preserve">
-    <value>The C# code contains a tab character</value>
+    <value>The code contains a tab or space character which is not consistent with the current project settings.</value>
   </data>
   <data name="SA1027MessageFormat" xml:space="preserve">
-    <value>Tabs must not be used.</value>
+    <value>Tabs and spaces should be used correctly</value>
   </data>
   <data name="SA1027Title" xml:space="preserve">
-    <value>Tabs must not be used</value>
+    <value>Use tabs correctly</value>
   </data>
   <data name="SA1028CodeFix" xml:space="preserve">
     <value>Remove trailing whitespace</value>

StyleCop.Analyzers/StyleCop.Analyzers/SpacingRules/SpacingResources.resx

@@ -316,7 +316,7 @@
     <Compile Include="SpacingRules\SA1024ColonsMustBeSpacedCorrectly.cs" />
     <Compile Include="SpacingRules\SA1025CodeMustNotContainMultipleWhitespaceInARow.cs" />
     <Compile Include="SpacingRules\SA1026CodeMustNotContainSpaceAfterNewKeywordInImplicitlyTypedArrayAllocation.cs" />
-    <Compile Include="SpacingRules\SA1027TabsMustNotBeUsed.cs" />
+    <Compile Include="SpacingRules\SA1027UseTabsCorrectly.cs" />
     <Compile Include="SpacingRules\SA1028CodeMustNotContainTrailingWhitespace.cs" />
     <Compile Include="SpacingRules\SpacingResources.Designer.cs">
       <AutoGen>True</AutoGen>

StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj

@@ -3,7 +3,7 @@
 <table>
 <tr>
   <td>TypeName</td>
-  <td>SA1027TabsMustNotBeUsed</td>
+  <td>SA1027UseTabsCorrectly</td>
 </tr>
 <tr>
   <td>CheckId</td>
@@ -17,19 +17,54 @@
 
 ## Cause
 
-The C# code contains a tab character.
+The code contains a tab or space character which is not consistent with the current project settings.
 
 ## Rule description
 
-A violation of this rule occurs whenever the code contains a tab character.
+A violation of this rule occurs whenever the code contains a tab or space character which is not consistent with the
+current project settings. By default, StyleCop Analyzers does not expect code to contain any tab characters. See
+[Configuration.md](Configuration.md) for information about changing this behavior via **stylecop.json**.
 
-Tabs should not be used within C# code, because the length of the tab character can vary depending upon the editor being used to view the code. This can cause the spacing and indexing of the code to vary from the developer's original intention, and can in some cases make the code difficult to read.
+In all configurations, this violation is always reported for tab characters that appear after the first non-whitespace
+character on a line. When tab characters are used in these positions, it is not possible to ensure that varying tab
+widths do not change the layout of code. See [Issue #2035](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2035)
+for more information.
 
-For these reasons, tabs should not be used, and each level of indentation should consist of four spaces. This will ensure that the code looks the same no matter which editor is being used to view the code.
+### Default behavior
+
+The default behavior matches the behavior of StyleCop Classic, which was based on the following rationale.
+
+> Tabs should not be used within C# code, because the length of the tab character can vary depending upon the editor being
+> used to view the code. This can cause the spacing and indexing of the code to vary from the developer's original
+> intention, and can in some cases make the code difficult to read.
+> 
+> For these reasons, tabs should not be used, and each level of indentation should consist of four spaces. This will
+> ensure that the code looks the same no matter which editor is being used to view the code.
+
+### Exclusions
+
+To avoid unintentionally changing the behavior of code, this violation is never reported in the following scenarios.
+
+* String literals, including interpolated string literals in C# 6
+
+* Character literals
+
+* Commented code (line comments starting with `////`). This ensures that literals within commented code are not changed.
+
+* Disabled text
+
+    ```csharp
+    #if DEBUG
+    This is ignored in debug configurations
+    #else
+    This is ignored in release configurations
+    #endif
+    ```
 
 ## How to fix violations
 
-To fix a violation of this rule, remove the tab character from the code.
+To fix a violation of this rule, use spaces or tabs to indent lines according to the project settings, and avoid the use
+of tabs aside from indentation.
 
 ## How to suppress violations