Implement new diagnostic SA1652 (EnableXmlDocumentationOutput)

Fixes DotNetAnalyzers#1053

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;
+
+    /// <summary>
+    /// Unit tests for <see cref="SA1652EnableXmlDocumentationOutput"/>.
+    /// </summary>
+    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);
+        }
+
+        /// <inheritdoc/>
+        protected override IEnumerable<DiagnosticAnalyzer> 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));
+        }
+    }
+}

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

@@ -142,6 +142,7 @@
     <Compile Include="DocumentationRules\SA1642UnitTests.cs" />
     <Compile Include="DocumentationRules\SA1643UnitTests.cs" />
     <Compile Include="DocumentationRules\SA1651UnitTests.cs" />
+    <Compile Include="DocumentationRules\SA1652UnitTests.cs" />
     <Compile Include="ExclusionTests.cs" />
     <Compile Include="ExportCodeFixProviderAttributeNameTest.cs" />
     <Compile Include="Helpers\CodeFixVerifier.Helper.cs" />

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/DocumentationResources.resx

@@ -129,4 +129,13 @@
   <data name="SA1651CodeFix" xml:space="preserve">
     <value>Finalize placeholder text</value>
   </data>
+  <data name="SA1652Description" xml:space="preserve">
+    <value>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.</value>
+  </data>
+  <data name="SA1652MessageFormat" xml:space="preserve">
+    <value>Enable XML documentation output</value>
+  </data>
+  <data name="SA1652Title" xml:space="preserve">
+    <value>Enable XML documentation output</value>
+  </data>
 </root>

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;
+
+    /// <summary>
+    /// The project is configured to not parse XML documentation comments.
+    /// </summary>
+    /// <remarks>
+    /// <para>A violation of this rule occurs when a compilation (project) contains one or more files which are parsed
+    /// with the <see cref="DocumentationMode"/> set to <see cref="DocumentationMode.None"/>. This most frequently
+    /// occurs when the project is configured to not produce an XML documentation file during the build.</para>
+    ///
+    /// <para>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.</para>
+    /// </remarks>
+    [DiagnosticAnalyzer(LanguageNames.CSharp)]
+    public class SA1652EnableXmlDocumentationOutput : DiagnosticAnalyzer
+    {
+        /// <summary>
+        /// The ID for diagnostics produced by the <see cref="SA1652EnableXmlDocumentationOutput"/> analyzer.
+        /// </summary>
+        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);
+
+        /// <inheritdoc/>
+        public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } =
+            ImmutableArray.Create(Descriptor);
+
+        /// <inheritdoc/>
+        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))));
+            }
+        }
+    }
+}

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

@@ -112,6 +112,7 @@
     <Compile Include="DocumentationRules\SA1650ElementDocumentationMustBeSpelledCorrectly.cs" />
     <Compile Include="DocumentationRules\SA1651CodeFixProvider.cs" />
     <Compile Include="DocumentationRules\SA1651DoNotUsePlaceholderElements.cs" />
+    <Compile Include="DocumentationRules\SA1652EnableXmlDocumentationOutput.cs" />
     <Compile Include="DocumentationRules\StandardTextDiagnosticBase.cs" />
     <Compile Include="GeneratedCodeAnalysisExtensions.cs" />
     <Compile Include="Helpers\DeclarationModifiersHelper.cs" />

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

documentation/SA1652.md

@@ -0,0 +1,56 @@
+# SA1652
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>SA1652EnableXmlDocumentationOutput</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>SA1652</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Documentation Rules</td>
+</tr>
+</table>
+
+## 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
+<PropertyGroup>
+  <!--
+    Make sure any documentation comments which are included in code get checked for syntax during the build, but do
+    not report warnings for missing comments.
+
+    CS1573: Parameter 'parameter' has no matching param tag in the XML comment for 'parameter' (but other parameters do)
+    CS1591: Missing XML comment for publicly visible type or member 'Type_or_Member'
+  -->
+  <DocumentationFile>$(OutputPath)$(AssemblyName).xml</DocumentationFile>
+  <NoWarn>$(NoWarn),1573,1591</NoWarn>
+</PropertyGroup>
+```
+
+## How to suppress violations
+
+This warning can only be suppressed by disabling the warning in the **ruleset** file for the project.