Merge pull request #1802 from sharwell/known-changes

Add information about known changes

Author: sharwell

README.md

@@ -17,6 +17,9 @@ The severity of individual rules may be configured using [rule set files](https:
 in Visual Studio 2015. **Settings.StyleCop** is not supported, but a **stylecop.json** file may be used to customize the
 behavior of certain rules. See [Configuration.md](documentation/Configuration.md) for more information.
 
+For users upgrading from StyleCop Classic, see [KnownChanges.md](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/tree/master/documentation/KnownChanges.md)
+for information about known differences which you may notice when switching to StyleCop Analyzers.
+
 ## Installation
 
 StyleCopAnalyzers can be installed using the NuGet Package Manager in Visual Studio 2015.

StyleCopAnalyzers.sln

@@ -35,6 +35,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "documentation", "documentat
 	ProjectSection(SolutionItems) = preProject
 		documentation\Configuration.md = documentation\Configuration.md
 		documentation\EnableConfiguration.md = documentation\EnableConfiguration.md
+		documentation\KnownChanges.md = documentation\KnownChanges.md
 		documentation\SA1000.md = documentation\SA1000.md
 		documentation\SA1001.md = documentation\SA1001.md
 		documentation\SA1002.md = documentation\SA1002.md

documentation/KnownChanges.md

@@ -0,0 +1,234 @@
+# Known Changes
+
+This document describes the known changes in behavior of StyleCop Analyzers relative to StyleCop Classic. The changes
+here meet all of the following conditions:
+
+1. The change in behavior affects code for C# 5 or earlier. StyleCop Classic did not support C# 6, so the necessary
+   changes made solely to support new language features are not considered here.
+2. The change in behavior is currently by-design. Unintentional changes in behavior are filed as bugs when they are
+   discovered.
+3. The change affects a rule which was present in StyleCop Classic. New rules introduced for StyleCop Analyzers can
+   be disabled for closer adherence to the behavior of StyleCop Classic.
+
+In many cases, the change in behavior was simply a change to the documentation, where the StyleCop Classic
+implementation deviated from its own documented rules. For completeness, these changes are included below whenever we
+found them. The following symbol is used to mark cases which are not simply a documentation error:
+
+> :warning: Cases where the StyleCop Analyzers implementation will produce different warnings from StyleCop Classic for
+the same code are marked with this symbol.
+
+## Disabled Rules
+
+Several rules present StyleCop Classic have been intentionally omitted from StyleCop Analyzers. The following table
+lists each of these issues, along with a link to the issue where the decision was made to omit the rule.
+
+| ID | Title | Issue |
+| --- | --- | --- |
+| SA1109 | Block statements must not contain embedded regions | [#998](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/998) |
+| SA1126 | Prefix calls correctly | [#59](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/59) |
+| SA1409 | Remove unnecessary code | [#1058](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1058) |
+| SA1603 | Documentation must contain valid XML | [#1291](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1291) |
+| SA1628 | Documentation text must begin with a capital letter | [#1057](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1057) |
+| SA1630 | Documentation text must contain whitespace | [#1057](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1057) |
+| SA1631 | Documentation must meet character percentage | [#1057](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1057) |
+| SA1632 | Documentation text must meet minimum character length | [#1057](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1057) |
+| SA1645 | Included documentation file does not exist | [#165](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/165) |
+| SA1646 | Included documentation XPath does not exist | [#166](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/166) |
+| SA1647 | Include node does not contain valid file and path | [#167](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/167) |
+| SA1650 | Element documentation must be spelled correctly | [#1057](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/1057) |
+
+## Spacing Rules
+
+### SA1000: Keywords must be spaced correctly
+
+The following changes were made to SA1000:
+
+1. :warning: A space is now required after `await` and `case`.
+
+2. An exception to the requirement that a space follow the `throw` keyword was added when it appears in a re-throw
+   statement. This exception was not mentioned in the documentation for StyleCop Classic.
+
+   ```csharp
+   throw;
+   ```
+
+3. :warning: An exception to the requirement that a space follow the `new` keyword was added when it appears as a
+   generic type constraint. StyleCop Classic did not check the spacing around the `new` keyword in a generic type
+   constraint.
+
+   ```csharp
+   public void Foo<T>() where T : IInterface, new()
+   {
+       // ...
+   }
+   ```
+
+### SA1001
+
+:warning: A slight change was made to the spacing around commas in open generic types. The following table demonstrates this
+change.
+
+| StyleCop Analyzers | StyleCop Classic |
+| --- | --- |
+| `typeof(Func<,>)` | `typeof(Func<, >)` |
+
+### SA1002
+
+:warning: StyleCop Classic required an infinite `for` loop to be written as follows:
+
+```csharp
+for (;;)
+{
+}
+```
+
+StyleCop Analyzers reports SA1002 for this same code, and instead requires the code be written as follows:
+
+```csharp
+for (; ;)
+{
+}
+```
+
+:bulb: When this code is encountered, users are encouraged to rewrite the code as follows for enhanced readability:
+
+```csharp
+while (true)
+{
+}
+```
+
+### SA1003
+
+:warning: StyleCop Classic allowed a type cast to appear at the end of a line, such as the following:
+
+```csharp
+uint value = (uint)
+    3;
+```
+
+StyleCop Analyzers forbids this same case, requiring the following instead:
+
+```csharp
+uint value = (uint)3;
+```
+
+### SA1025
+
+StyleCop Classic allowed multiple spaces to precede a comment placed at the end of a line, such as the following:
+
+```csharp
+int x;    // comment
+```
+
+StyleCop Analyzers does not currently make an exception to the SA1025 rule for this case, although this decision is
+still under review.
+
+## Readability Rules
+
+### SA1110, SA1111, SA1113, SA1114
+
+StyleCop Analyzers examines several constructs which are not mentioned in the original documentation for these rules:
+
+* Delegate declarations
+* Anonymous method expressions
+* Lambda expressions
+
+### SA1119
+
+:warning: StyleCop Classic did not report SA1119 for the following code:
+
+```csharp
+var a = (new[] { 1, 2, 3 }).ToArray();
+```
+
+StyleCop Analyzers reports SA1119 for this same code, and requires the following change to correct it:
+
+```csharp
+var a = new[] { 1, 2, 3 }.ToArray();
+```
+
+## Ordering Rules
+
+There are no known changes at this time.
+
+## Naming Rules
+
+### SA1305
+
+This rule is disabled by default in StyleCop Analyzers, but can be enabled by users via a rule set file.
+
+## Maintainability Rules
+
+There are no known changes at this time.
+
+## Layout Rules
+
+### SA1515
+
+:warning: The following code does not report a warning in StyleCop Classic:
+
+```csharp
+[ContractClassFor(typeof(ILinkActivator<>))]
+// ReSharper disable once InconsistentNaming
+// Contract class containing only metadata pertaining to an interface.
+// Using naming convention adopted by the Code Contracts team for .NET framework contracts.
+public abstract class ILinkActivatorContract<T> : ILinkActivator<T> where T : LinkTemplate
+```
+
+StyleCop Analyzers reports SA1515 for this code, and instead requires the following:
+
+```csharp
+[ContractClassFor(typeof(ILinkActivator<>))]
+
+// ReSharper disable once InconsistentNaming
+// Contract class containing only metadata pertaining to an interface.
+// Using naming convention adopted by the Code Contracts team for .NET framework contracts.
+public abstract class ILinkActivatorContract<T> : ILinkActivator<T> where T : LinkTemplate
+```
+
+## Documentation Rules
+
+### SA1642
+
+StyleCop Analyzers requires the use of a `<see>` element when referencing the class name in the standard constructor
+text. In StyleCop Classic, this element was optional.
+
+StyleCop Classic included a special case for constructor text used for `private` constructors. StyleCop Analyzers still
+allows users to use this wording in the documentation of private constructors, but prefers the use of the standard
+constructor text. When the code fix for SA1642 is applied to a private constructor, the inserted text will comply with
+StyleCop Analyzers but will result in a warning in StyleCop Classic. For example:
+
+The following code does not produce a warning in StyleCop Classic or StyleCop Analyzers:
+
+```csharp
+public class ApiStatus
+{
+    /// <summary>
+    /// Prevents a default instance of the <see cref="ApiStatus"/> class from being created.
+    /// </summary>
+    private ApiStatus()
+    {
+    }
+}
+```
+
+:warning: The following code produces a warning in StyleCop Classic, but does not produce a warning in StyleCop Analyzers:
+
+```csharp
+public class ApiStatus
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ApiStatus"/> class.
+    /// </summary>
+    private ApiStatus()
+    {
+    }
+}
+```
+
+### SA1649
+
+StyleCop Analyzers modified SA1649 to check the first type against the actual file name as opposed to checking against a
+value which appeared in the file header. For StyleCop Classic users who had both SA1638 and SA1649 enabled, this change
+does not produce any new warnings in code which previously complied with StyleCop.

documentation/SA1000.md

@@ -23,11 +23,21 @@ The spacing around a C# keyword is incorrect.
 
 A violation of this rule occurs when the spacing around a keyword is incorrect.
 
-The following C# keywords must always be followed by a single space: *catch, fixed, for, foreach, from, group, if, in, into, join, let, lock, orderby, return, select, stackalloc, switch, throw, using, where, while, yield*.
+The following C# keywords must always be followed by a single space: `await`, `case`, `catch`, `fixed`, `for`,
+`foreach`, `from`, `group`, `if`, `in`, `into`, `join`, `let`, `lock`, `orderby`, `return`, `select`, `stackalloc`,
+`switch`, `using`, `where`, `while`, `yield`.
 
-The following keywords must not be followed by any space: *checked, default, sizeof, typeof, unchecked*.
+The following keywords must not be followed by any space: `checked`, `default`, `sizeof`, `typeof`, `unchecked`.
 
-The *new* keyword should always be followed by a space, unless it is used to create a new array, in which case there should be no space between the *new* keyword and the opening array bracket.
+The `new` keyword should always be followed by a space, except in the following cases:
+
+* The `new` keyword is used to create a new array. In this case there should be no space between the `new` keyword and
+  the opening array bracket.
+* The `new` keyword is part of a generic type constraint. In this case there should be no space between the `new`
+  keyword and the opening parenthesis.
+
+The `throw` keyword should always be followed by a space, unless it is part of a re-throw statement, in which case there
+should be no space between the `throw` keyword and the semicolon.
 
 ## How to fix violations
 

documentation/SA1001.md

@@ -23,7 +23,12 @@ The spacing around a comma is incorrect, within a C# code file.
 
 A violation of this rule occurs when the spacing around a comma is incorrect.
 
-A comma should always be followed by a single space, unless it is the last character on the line, and a comma should never be preceded by any whitespace.
+A comma should be followed by a single space, except in the following cases.
+
+* A comma may appear at the end of a line
+* A comma should not be followed by a space when used in an open generic type in a `typeof` expression
+
+A comma must never be preceded by a space or appear as the first token on a line.
 
 ## How to fix violations
 

documentation/SA1002.md

@@ -23,7 +23,12 @@ The spacing around a semicolon is incorrect, within a C# code file.
 
 A violation of this rule occurs when the spacing around a semicolon is incorrect.
 
-A semicolon should always be followed by a single space, unless it is the last character on the line, and a semicolon should never be preceded by any whitespace, unless it is the first character on the line.
+A semicolon should always be followed by a single space, except in the following cases:
+
+* The semicolon is the last character on the line
+* The semicolon followed by a closing parenthesis
+
+A semicolon should never be preceded by any whitespace, unless it is the first character on the line.
 
 ## How to fix violations
 

documentation/SA1003.md

@@ -23,7 +23,9 @@ The spacing around an operator symbol is incorrect, within a C# code file.
 
 A violation of this rule occurs when the spacing around an operator symbol is incorrect.
 
-The following types of operator symbols must be surrounded by a single space on either side: colons, arithmetic operators, assignment operators, conditional operators, logical operators, relational operators, shift operators, and lambda operators. For example:
+The following types of operator symbols must be surrounded by a single space on either side: colons, arithmetic
+operators, assignment operators, conditional operators, logical operators, relational operators, shift operators, and
+lambda operators. For example:
 
 ```csharp
 int x = 4 + y;
@@ -35,7 +37,8 @@ In contrast, unary operators must be preceded by a single space, but must never
 bool x = !value;
 ```
 
-An exception occurs whenever the symbol is preceded or followed by a parenthesis or bracket, in which case there should be no space between the symbol and the bracket. For example:
+An exception occurs whenever the symbol is preceded or followed by a parenthesis or bracket, in which case there should
+be no space between the symbol and the bracket. For example:
 
 ```csharp
 if (!value)

documentation/SA1025.md

@@ -21,8 +21,8 @@ The code contains multiple whitespace characters in a row.
 
 ## Rule description
 
-A violation of this rule occurs whenever the code contains multiple whitespace characters in a row, unless the characters come at the beginning or end of a line of code, 
-                    following a comma or semicolon or preceeding a symbol.
+A violation of this rule occurs whenever the code contains multiple whitespace characters in a row, unless the
+characters come at the beginning or end of a line of code, following a comma or semicolon or preceding a symbol.
 
 ## How to fix violations
 

documentation/SA1028.md

@@ -15,6 +15,8 @@
 </tr>
 </table>
 
+:memo: This rule is new for StyleCop Analyzers, and was not present in StyleCop Classic.
+
 ## Cause
 
 A line of code ends with a space, tab, or other whitespace characters before the end of line character(s).

documentation/SA1109.md

@@ -15,6 +15,9 @@
 </tr>
 </table>
 
+:warning: This rule has been intentionally omitted from StyleCop Analyzers. See [KnownChanges.md](KnownChanges.md) for
+additional information.
+
 ## Cause
 
 A C# statement contains a region tag between the declaration of the statement and the opening brace of the statement.