From 07be15b3c954bfb85a2607ec8bbef5f9227ad9d5 Mon Sep 17 00:00:00 2001 From: Sam Harwell Date: Sun, 26 Jul 2015 14:40:39 -0500 Subject: [PATCH] Implement new diagnostic SA1652 (EnableXmlDocumentationOutput) Fixes #1053 --- .../DocumentationRules/SA1652UnitTests.cs | 65 +++++++++++++++++++ .../StyleCop.Analyzers.Test.csproj | 1 + .../DocumentationResources.Designer.cs | 27 ++++++++ .../DocumentationResources.resx | 9 +++ .../SA1652EnableXmlDocumentationOutput.cs | 53 +++++++++++++++ .../StyleCop.Analyzers.csproj | 1 + StyleCopAnalyzers.sln | 1 + documentation/SA1652.md | 56 ++++++++++++++++ 8 files changed, 213 insertions(+) create mode 100644 StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1652UnitTests.cs create mode 100644 StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1652EnableXmlDocumentationOutput.cs create mode 100644 documentation/SA1652.md diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1652UnitTests.cs b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1652UnitTests.cs new file mode 100644 index 000000000..af908f26d --- /dev/null +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1652UnitTests.cs @@ -0,0 +1,65 @@ +namespace StyleCop.Analyzers.Test.DocumentationRules +{ + using System.Collections.Generic; + using System.Threading; + using System.Threading.Tasks; + using Analyzers.DocumentationRules; + using Microsoft.CodeAnalysis; + using Microsoft.CodeAnalysis.Diagnostics; + using TestHelper; + using Xunit; + + /// + /// Unit tests for . + /// + public class SA1652UnitTests : DiagnosticVerifier + { + private DocumentationMode documentationMode; + + [Theory] + [InlineData(DocumentationMode.Diagnose)] + public async Task TestEnabledDocumentationModesAsync(DocumentationMode documentationMode) + { + var testCode = @"public class Foo +{ +} +"; + + this.documentationMode = documentationMode; + await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false); + } + + [Theory] + [InlineData(DocumentationMode.None)] + [InlineData(DocumentationMode.Parse)] + public async Task TestDisabledDocumentationModesAsync(DocumentationMode documentationMode) + { + var testCode = @"public class Foo +{ +} +"; + + DiagnosticResult[] expected = + { + this.CSharpDiagnostic().WithLocation(0, 0) + }; + + this.documentationMode = documentationMode; + await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false); + } + + /// + protected override IEnumerable GetCSharpDiagnosticAnalyzers() + { + yield return new SA1652EnableXmlDocumentationOutput(); + } + + protected override Solution CreateSolution(ProjectId projectId, string language) + { + Solution solution = base.CreateSolution(projectId, language); + Project project = solution.GetProject(projectId); + + return solution.WithProjectParseOptions(projectId, project.ParseOptions.WithDocumentationMode(this.documentationMode)); + } + } +} diff --git a/StyleCop.Analyzers/StyleCop.Analyzers.Test/StyleCop.Analyzers.Test.csproj b/StyleCop.Analyzers/StyleCop.Analyzers.Test/StyleCop.Analyzers.Test.csproj index e4e96311f..d56296b3c 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers.Test/StyleCop.Analyzers.Test.csproj +++ b/StyleCop.Analyzers/StyleCop.Analyzers.Test/StyleCop.Analyzers.Test.csproj @@ -142,6 +142,7 @@ + diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.Designer.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.Designer.cs index 5c857983a..2dda1d407 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.Designer.cs +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.Designer.cs @@ -96,5 +96,32 @@ internal static string SA1651CodeFix { return ResourceManager.GetString("SA1651CodeFix", resourceCulture); } } + + /// + /// Looks up a localized string similar to The project is currently configured to not parse XML documentation comments; all diagnostics for documentation comments are disabled. Enable XML documentation output to enable these diagnostics.. + /// + internal static string SA1652Description { + get { + return ResourceManager.GetString("SA1652Description", resourceCulture); + } + } + + /// + /// Looks up a localized string similar to Enable XML documentation output. + /// + internal static string SA1652MessageFormat { + get { + return ResourceManager.GetString("SA1652MessageFormat", resourceCulture); + } + } + + /// + /// Looks up a localized string similar to Enable XML documentation output. + /// + internal static string SA1652Title { + get { + return ResourceManager.GetString("SA1652Title", resourceCulture); + } + } } } diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.resx b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.resx index ca8352445..0bcfabcd5 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.resx +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.resx @@ -129,4 +129,13 @@ Finalize placeholder text + + The project is currently configured to not parse XML documentation comments; all diagnostics for documentation comments are disabled. Enable XML documentation output to enable these diagnostics. + + + Enable XML documentation output + + + Enable XML documentation output + \ No newline at end of file diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1652EnableXmlDocumentationOutput.cs b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1652EnableXmlDocumentationOutput.cs new file mode 100644 index 000000000..a9ed1d8d5 --- /dev/null +++ b/StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1652EnableXmlDocumentationOutput.cs @@ -0,0 +1,53 @@ +namespace StyleCop.Analyzers.DocumentationRules +{ + using System.Collections.Immutable; + using Microsoft.CodeAnalysis; + using Microsoft.CodeAnalysis.Diagnostics; + using Microsoft.CodeAnalysis.Text; + + /// + /// The project is configured to not parse XML documentation comments. + /// + /// + /// A violation of this rule occurs when a compilation (project) contains one or more files which are parsed + /// with the set to . This most frequently + /// occurs when the project is configured to not produce an XML documentation file during the build. + /// + /// Each project should be configured to include an XML documentation file with the compiled output. + /// Otherwise, the semantics of all documentation comments are not checked and comments are likely to contain an + /// increasing number of errors over time. + /// + [DiagnosticAnalyzer(LanguageNames.CSharp)] + public class SA1652EnableXmlDocumentationOutput : DiagnosticAnalyzer + { + /// + /// The ID for diagnostics produced by the analyzer. + /// + public const string DiagnosticId = "SA1652"; + private static readonly LocalizableString Title = new LocalizableResourceString(nameof(DocumentationResources.SA1652Title), DocumentationResources.ResourceManager, typeof(DocumentationResources)); + private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(DocumentationResources.SA1652MessageFormat), DocumentationResources.ResourceManager, typeof(DocumentationResources)); + private static readonly LocalizableString Description = new LocalizableResourceString(nameof(DocumentationResources.SA1652Description), DocumentationResources.ResourceManager, typeof(DocumentationResources)); + private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1652.md"; + + private static readonly DiagnosticDescriptor Descriptor = + new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink); + + /// + public override ImmutableArray SupportedDiagnostics { get; } = + ImmutableArray.Create(Descriptor); + + /// + public override void Initialize(AnalysisContext context) + { + context.RegisterSyntaxTreeActionHonorExclusions(HandleSyntaxTree); + } + + private static void HandleSyntaxTree(SyntaxTreeAnalysisContext context) + { + if (context.Tree.Options.DocumentationMode == DocumentationMode.None) + { + context.ReportDiagnostic(Diagnostic.Create(Descriptor, context.Tree.GetLocation(new TextSpan(0, 0)))); + } + } + } +} diff --git a/StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj b/StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj index b6f0dc02e..bda03b67c 100644 --- a/StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj +++ b/StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj @@ -112,6 +112,7 @@ + diff --git a/StyleCopAnalyzers.sln b/StyleCopAnalyzers.sln index b2478daa1..933e81677 100644 --- a/StyleCopAnalyzers.sln +++ b/StyleCopAnalyzers.sln @@ -44,6 +44,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "documentation", "documentat documentation\SA1519.md = documentation\SA1519.md documentation\SA1520.md = documentation\SA1520.md documentation\SA1651.md = documentation\SA1651.md + documentation\SA1652.md = documentation\SA1652.md documentation\SX1309.md = documentation\SX1309.md documentation\SX1309S.md = documentation\SX1309S.md EndProjectSection diff --git a/documentation/SA1652.md b/documentation/SA1652.md new file mode 100644 index 000000000..57d65aab3 --- /dev/null +++ b/documentation/SA1652.md @@ -0,0 +1,56 @@ +# SA1652 + + + + + + + + + + + + + + +
TypeNameSA1652EnableXmlDocumentationOutput
CheckIdSA1652
CategoryDocumentation Rules
+ +## Cause + +The project is configured to not parse XML documentation comments. + +## Rule description + +A violation of this rule occurs when a compilation (project) contains one or more files which are parsed with the +`DocumentationMode` set to `None`. This most frequently occurs when the project is configured to not produce an XML +documentation file during the build. + +Each project should be configured to include an XML documentation file with the compiled output. Otherwise, the +semantics of all documentation comments are not checked and comments are likely to contain an increasing number of +errors over time. + +## How to fix violations + +To fix a violation of this rule, enable the XML documentation file as part of the project output. + +**Note:** In some cases, enabling XML documentation output will produce a large number of warnings CS1573 and/or CS1591 +to be reported. To improve the ability of teams to resolve SA1652 before CS1573 and/or CS1591, consider editing the +project file to include the following property group. + +```xml + + + $(OutputPath)$(AssemblyName).xml + $(NoWarn),1573,1591 + +``` + +## How to suppress violations + +This warning can only be suppressed by disabling the warning in the **ruleset** file for the project.