Merge remote-tracking branch 'DotNetAnalyzers/master' into fix-2023

Author: sharwell

CONTRIBUTING.md

@@ -5,8 +5,6 @@ If you want to contribute code you can get started by looking for issues marked
 We also have the [easy](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/labels/easy) tag
 for issues suitable if you are unfamiliar with roslyn.
 
-Also see the [contributing guide](CONTRIBUTING.md).
-
 You can also help by filing issues, participating in discussions and doing code review.
 
 ## Implementing a diagnostic
@@ -30,4 +28,4 @@ You can also help by filing issues, participating in discussions and doing code
 
 Visual Studio 2015 RC is required for building this repository.
 The Visual Studio 2015 RC SDK is required for building the vsix extension project and for
-debugging in an experimental visual studio hive.
+debugging in an experimental visual studio hive.

DOCUMENTATION.md

@@ -0,0 +1,51 @@
+StyleCop.Analyzers provides warnings that indicate style and consistency rule violations in C# code. The warnings are organized into rule areas such as documentation, layout, naming, ordering, readability, spacing, and so forth. Each warning signifies a violation of a style or consistency rule. This section provides an explanation of each of the default StyleCop.Analyzers rules. 
+
+### Rule areas
+**[Special Rules (SA0000-)](documentation/SpecialRules.md)**
+
+Rules which provide special functionality like workarounds, configuration errors, etc.
+
+**[Spacing Rules (SA1000-)](documentation/SpacingRules.md)**
+
+Rules which enforce spacing requirements around keywords and symbols in the code.
+
+**[Readability Rules (SA1100-)](documentation/ReadabilityRules.md)**
+
+Rules which ensure that the code is well-formatted and readable.
+
+**[Ordering Rules (SA1200-)](documentation/OrderingRules.md)**
+
+Rules which enforce a standard ordering scheme for code contents.
+
+**[Naming Rules (SA1300-)](documentation/NamingRules.md)**
+
+Rules which enforce naming requirements for members, types, and variables.
+
+**[Maintainability Rules (SA1400-)](documentation/MaintainabilityRules.md)**
+
+Rules which improve code maintainability.
+
+**[Layout Rules (SA1500-)](documentation/LayoutRules.md)**
+
+Rules which enforce code layout and line spacing.
+
+**[Documentation Rules (SA1600-)](documentation/DocumentationRules.md)**
+
+Rules which verify the content and formatting of code documentation.
+
+**[Alternative Rules (SX0000-)](documentation/AlternativeRules.md)**
+
+Rules which offer a non-standard extension to the default StyleCop behavior.
+
+### Additional documentation
+**[Configuration](documentation/Configuration.md)**
+
+Describes the configuration options for StyleCop.Analyzers
+
+**[How to enable the configuration](documentation/EnableConfiguration.md)**
+
+Describes how to enable the **stylecop.json** file for usage.
+
+**[Known changes](documentation/KnownChanges.md)**
+
+Describes the known differences between StyleCop Analyzers and StyleCop Classic.

README.md

@@ -22,8 +22,14 @@ for information about known differences which you may notice when switching to S
 
 ## Installation
 
-StyleCopAnalyzers can be installed using the NuGet Package Manager in Visual Studio 2015.
+StyleCopAnalyzers can be installed using the NuGet command line or the NuGet Package Manager in Visual Studio 2015.
 
+**Install using the command line:**
+```bash
+Install-Package StyleCop.Analyzers
+```
+
+**Install using the package manager:**
 ![Install via nuget](https://cloud.githubusercontent.com/assets/1408396/8233513/491f301a-159c-11e5-8b7a-1e16a0695da6.png)
 
 ## Team Considerations

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/FileHeaderCodeFixProvider.cs

@@ -4,6 +4,7 @@
 namespace StyleCop.Analyzers.DocumentationRules
 {
     using System;
+    using System.Collections.Generic;
     using System.Collections.Immutable;
     using System.Composition;
     using System.Text;
@@ -18,6 +19,7 @@ namespace StyleCop.Analyzers.DocumentationRules
     using Microsoft.CodeAnalysis.Formatting;
     using StyleCop.Analyzers.Helpers;
     using StyleCop.Analyzers.Settings.ObjectModel;
+    using Path = System.IO.Path;
 
     /// <summary>
     /// Implements a code fix for file header diagnostics.
@@ -136,8 +138,9 @@ private static SyntaxNode ReplaceWellFormedMultiLineCommentHeader(Document docum
             // Pad line that used to be next to a /*
             triviaStringParts[0] = commentIndentation + interlinePadding + " " + triviaStringParts[0];
             StringBuilder sb = StringBuilderPool.Allocate();
+            string fileName = Path.GetFileName(document.FilePath);
             var copyrightText = commentIndentation + interlinePadding + " " +
-                GetCopyrightText(commentIndentation + interlinePadding, settings.DocumentationRules.CopyrightText, newLineText);
+                GetCopyrightText(commentIndentation + interlinePadding, settings.DocumentationRules.GetCopyrightText(fileName), newLineText);
             var newHeader = WrapInXmlComment(commentIndentation + interlinePadding, copyrightText, document.Name, settings, newLineText);
 
             sb.Append(commentIndentation);
@@ -212,6 +215,9 @@ private static SyntaxNode ReplaceHeader(Document document, SyntaxNode root, Styl
             var leadingSpaces = string.Empty;
             string possibleLeadingSpaces = string.Empty;
 
+            // remove header decoration lines, they will be re-generated
+            trivia = RemoveHeaderDecorationLines(trivia, settings);
+
             // Need to do this with index so we get the line endings correct.
             for (int i = 0; i < trivia.Count; i++)
             {
@@ -350,31 +356,71 @@ private static SyntaxNode AddHeader(Document document, SyntaxNode root, string n
             return root.WithLeadingTrivia(newTrivia);
         }
 
-        private static SyntaxTriviaList CreateNewHeader(string prefixWithLeadingSpaces, string filename, StyleCopSettings settings, string newLineText)
+        private static SyntaxTriviaList CreateNewHeader(string prefixWithLeadingSpaces, string fileName, StyleCopSettings settings, string newLineText)
         {
-            var copyrightText = prefixWithLeadingSpaces + " " + GetCopyrightText(prefixWithLeadingSpaces, settings.DocumentationRules.CopyrightText, newLineText);
+            var copyrightText = prefixWithLeadingSpaces + " " + GetCopyrightText(prefixWithLeadingSpaces, settings.DocumentationRules.GetCopyrightText(fileName), newLineText);
             var newHeader = settings.DocumentationRules.XmlHeader
-                ? WrapInXmlComment(prefixWithLeadingSpaces, copyrightText, filename, settings, newLineText)
+                ? WrapInXmlComment(prefixWithLeadingSpaces, copyrightText, fileName, settings, newLineText)
                 : copyrightText;
             return SyntaxFactory.ParseLeadingTrivia(newHeader);
         }
 
-        private static string WrapInXmlComment(string prefixWithLeadingSpaces, string copyrightText, string filename, StyleCopSettings settings, string newLineText)
+        private static string WrapInXmlComment(string prefixWithLeadingSpaces, string copyrightText, string fileName, StyleCopSettings settings, string newLineText)
         {
-            string encodedFilename = new XAttribute("t", filename).ToString().Substring(2).Trim('"');
+            string encodedFilename = new XAttribute("t", fileName).ToString().Substring(2).Trim('"');
             string encodedCompanyName = new XAttribute("t", settings.DocumentationRules.CompanyName).ToString().Substring(2).Trim('"');
             string encodedCopyrightText = new XText(copyrightText).ToString();
 
-            return
+            string copyrightString =
                 $"{prefixWithLeadingSpaces} <copyright file=\"{encodedFilename}\" company=\"{encodedCompanyName}\">" + newLineText
                 + encodedCopyrightText + newLineText
                 + prefixWithLeadingSpaces + " </copyright>";
+
+            if (!string.IsNullOrEmpty(settings.DocumentationRules.HeaderDecoration))
+            {
+                return
+                    $"{prefixWithLeadingSpaces} {settings.DocumentationRules.HeaderDecoration}" + newLineText
+                    + copyrightString + newLineText
+                    + $"{prefixWithLeadingSpaces} {settings.DocumentationRules.HeaderDecoration}";
+            }
+
+            return copyrightString;
         }
 
         private static string GetCopyrightText(string prefixWithLeadingSpaces, string copyrightText, string newLineText)
         {
             copyrightText = copyrightText.Replace("\r\n", "\n");
             return string.Join(newLineText + prefixWithLeadingSpaces + " ", copyrightText.Split('\n')).Replace(prefixWithLeadingSpaces + " " + newLineText, prefixWithLeadingSpaces + newLineText);
         }
+
+        private static SyntaxTriviaList RemoveHeaderDecorationLines(SyntaxTriviaList trivia, StyleCopSettings settings)
+        {
+            if (!string.IsNullOrEmpty(settings.DocumentationRules.HeaderDecoration))
+            {
+                var decorationRemovalList = new List<int>();
+                for (int i = 0; i < trivia.Count; i++)
+                {
+                    var triviaLine = trivia[i];
+                    if (triviaLine.Kind() == SyntaxKind.SingleLineCommentTrivia && triviaLine.ToFullString().Contains(settings.DocumentationRules.HeaderDecoration))
+                    {
+                        decorationRemovalList.Add(i);
+
+                        // also remove the line break
+                        if (i + 1 < trivia.Count && trivia[i + 1].Kind() == SyntaxKind.EndOfLineTrivia)
+                        {
+                            decorationRemovalList.Add(i + 1);
+                        }
+                    }
+                }
+
+                // Remove decoration lines in reverse order.
+                for (int i = decorationRemovalList.Count - 1; i >= 0; i--)
+                {
+                    trivia = trivia.RemoveAt(decorationRemovalList[i]);
+                }
+            }
+
+            return trivia;
+        }
     }
 }

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/SA1609SA1610CodeFixProvider.cs

@@ -44,12 +44,15 @@ public override Task RegisterCodeFixesAsync(CodeFixContext context)
         {
             foreach (var diagnostic in context.Diagnostics)
             {
-                context.RegisterCodeFix(
-                    CodeAction.Create(
-                        DocumentationResources.SA1609SA1610CodeFix,
-                        cancellationToken => this.GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
-                        nameof(SA1609SA1610CodeFixProvider)),
-                    diagnostic);
+                if (!diagnostic.Properties.ContainsKey(PropertyDocumentationBase.NoCodeFixKey))
+                {
+                    context.RegisterCodeFix(
+                        CodeAction.Create(
+                            DocumentationResources.SA1609SA1610CodeFix,
+                            cancellationToken => this.GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
+                            nameof(SA1609SA1610CodeFixProvider)),
+                        diagnostic);
+                }
             }
 
             return SpecializedTasks.CompletedTask;

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/SA1615SA1616CodeFixProvider.cs

@@ -75,7 +75,13 @@ private static async Task<Document> GetTransformedDocumentAsync(Document documen
             DocumentationCommentTriviaSyntax documentationComment =
                 methodDeclarationSyntax?.GetDocumentationCommentTriviaSyntax()
                 ?? delegateDeclarationSyntax?.GetDocumentationCommentTriviaSyntax();
-            if (documentationComment == null)
+            bool canIgnoreDocumentation =
+                documentationComment == null
+                || documentationComment.Content
+                    .Where(x => x is XmlElementSyntax || x is XmlEmptyElementSyntax)
+                    .All(x => string.Equals(x.GetName()?.ToString(), XmlCommentHelper.IncludeXmlTag));
+
+            if (canIgnoreDocumentation)
             {
                 return document;
             }

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/SA1617CodeFixProvider.cs

@@ -39,12 +39,15 @@ public override Task RegisterCodeFixesAsync(CodeFixContext context)
         {
             foreach (Diagnostic diagnostic in context.Diagnostics)
             {
-                context.RegisterCodeFix(
-                    CodeAction.Create(
-                        DocumentationResources.SA1617CodeFix,
-                        cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
-                        nameof(SA1617CodeFixProvider)),
-                    diagnostic);
+                if (!diagnostic.Properties.ContainsKey(SA1617VoidReturnValueMustNotBeDocumented.NoCodeFixKey))
+                {
+                    context.RegisterCodeFix(
+                        CodeAction.Create(
+                            DocumentationResources.SA1617CodeFix,
+                            cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
+                            nameof(SA1617CodeFixProvider)),
+                        diagnostic);
+                }
             }
 
             return SpecializedTasks.CompletedTask;

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/SA1642SA1643CodeFixProvider.cs

@@ -6,8 +6,10 @@ namespace StyleCop.Analyzers.DocumentationRules
     using System;
     using System.Collections.Immutable;
     using System.Composition;
+    using System.Globalization;
     using System.Linq;
     using System.Text.RegularExpressions;
+    using System.Threading;
     using System.Threading.Tasks;
     using Helpers;
     using Microsoft.CodeAnalysis;
@@ -48,16 +50,20 @@ public override async Task RegisterCodeFixesAsync(CodeFixContext context)
 
             foreach (var diagnostic in context.Diagnostics)
             {
-                var node = root.FindNode(diagnostic.Location.SourceSpan, findInsideTrivia: true, getInnermostNodeForTie: true);
+                if (diagnostic.Properties.ContainsKey(StandardTextDiagnosticBase.NoCodeFixKey))
+                {
+                    continue;
+                }
 
+                var node = root.FindNode(diagnostic.Location.SourceSpan, findInsideTrivia: true, getInnermostNodeForTie: true);
                 var xmlElementSyntax = node as XmlElementSyntax;
 
                 if (xmlElementSyntax != null)
                 {
                     context.RegisterCodeFix(
                         CodeAction.Create(
                             DocumentationResources.SA1642SA1643CodeFix,
-                            cancellationToken => GetTransformedDocumentAsync(context.Document, root, xmlElementSyntax),
+                            cancellationToken => GetTransformedDocumentAsync(context.Document, root, xmlElementSyntax, cancellationToken),
                             nameof(SA1642SA1643CodeFixProvider)),
                         diagnostic);
                 }
@@ -74,11 +80,14 @@ public override async Task RegisterCodeFixesAsync(CodeFixContext context)
             }
         }
 
-        private static Task<Document> GetTransformedDocumentAsync(Document document, SyntaxNode root, XmlElementSyntax node)
+        private static Task<Document> GetTransformedDocumentAsync(Document document, SyntaxNode root, XmlElementSyntax node, CancellationToken cancellationToken)
         {
             var typeDeclaration = node.FirstAncestorOrSelf<BaseTypeDeclarationSyntax>();
             var declarationSyntax = node.FirstAncestorOrSelf<BaseMethodDeclarationSyntax>();
             bool isStruct = typeDeclaration.IsKind(SyntaxKind.StructDeclaration);
+            var settings = document.Project.AnalyzerOptions.GetStyleCopSettings(cancellationToken);
+            var culture = new CultureInfo(settings.DocumentationRules.DocumentationCulture);
+            var resourceManager = DocumentationResources.ResourceManager;
 
             TypeParameterListSyntax typeParameterList;
             ClassDeclarationSyntax classDeclaration = typeDeclaration as ClassDeclarationSyntax;
@@ -94,35 +103,29 @@ private static Task<Document> GetTransformedDocumentAsync(Document document, Syn
             ImmutableArray<string> standardText;
             if (declarationSyntax is ConstructorDeclarationSyntax)
             {
+                var typeKindText = resourceManager.GetString(isStruct ? nameof(DocumentationResources.TypeTextStruct) : nameof(DocumentationResources.TypeTextClass), culture);
                 if (declarationSyntax.Modifiers.Any(SyntaxKind.StaticKeyword))
                 {
-                    if (isStruct)
-                    {
-                        standardText = ImmutableArray.Create(SA1642ConstructorSummaryDocumentationMustBeginWithStandardText.StaticConstructorStandardText, " struct.");
-                    }
-                    else
-                    {
-                        standardText = ImmutableArray.Create(SA1642ConstructorSummaryDocumentationMustBeginWithStandardText.StaticConstructorStandardText, " class.");
-                    }
+                    standardText = ImmutableArray.Create(
+                        string.Format(resourceManager.GetString(nameof(DocumentationResources.StaticConstructorStandardTextFirstPart), culture), typeKindText),
+                        string.Format(resourceManager.GetString(nameof(DocumentationResources.StaticConstructorStandardTextSecondPart), culture), typeKindText));
                 }
                 else
                 {
                     // Prefer to insert the "non-private" wording for all constructors, even though both are considered
                     // acceptable for private constructors by the diagnostic.
                     // https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/413
-                    if (isStruct)
-                    {
-                        standardText = ImmutableArray.Create(SA1642ConstructorSummaryDocumentationMustBeginWithStandardText.NonPrivateConstructorStandardText, " struct.");
-                    }
-                    else
-                    {
-                        standardText = ImmutableArray.Create(SA1642ConstructorSummaryDocumentationMustBeginWithStandardText.NonPrivateConstructorStandardText, " class.");
-                    }
+                    standardText = ImmutableArray.Create(
+                        string.Format(resourceManager.GetString(nameof(DocumentationResources.NonPrivateConstructorStandardTextFirstPart), culture), typeKindText),
+                        string.Format(resourceManager.GetString(nameof(DocumentationResources.NonPrivateConstructorStandardTextSecondPart), culture), typeKindText));
                 }
             }
             else if (declarationSyntax is DestructorDeclarationSyntax)
             {
-                standardText = SA1643DestructorSummaryDocumentationMustBeginWithStandardText.DestructorStandardText;
+                standardText =
+                    ImmutableArray.Create(
+                        resourceManager.GetString(nameof(DocumentationResources.DestructorStandardTextFirstPart), culture),
+                        resourceManager.GetString(nameof(DocumentationResources.DestructorStandardTextSecondPart), culture));
             }
             else
             {