Add PlaceholderDocumentation analyzer and code fix

This analyzer reports a warning for the use of <placeholder> elements
in a documentation comment. If the element contains text, a code fix
is also provided which allows the contents to be "finalized" by simply
removing the start and end placeholder tags.

Fixes #10

Author: sharwell

OpenStackNetAnalyzers/OpenStackNetAnalyzers/OpenStackNetAnalyzers.csproj

@@ -42,6 +42,8 @@
     <Compile Include="JsonPropertyDefaultValueHandlingAnalyzer.cs" />
     <Compile Include="JsonPropertyDefaultValueHandlingCodeFix.cs" />
     <Compile Include="NonNullableJsonPropertyAnalyzer.cs" />
+    <Compile Include="PlaceholderDocumentationAnalyzer.cs" />
+    <Compile Include="PlaceholderDocumentationCodeFix.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="SpacingExtensions.cs" />
     <Compile Include="XmlSyntaxFactory.cs" />

OpenStackNetAnalyzers/OpenStackNetAnalyzers/PlaceholderDocumentationAnalyzer.cs

@@ -0,0 +1,57 @@
+namespace OpenStackNetAnalyzers
+{
+    using System;
+    using System.Collections.Immutable;
+    using Microsoft.CodeAnalysis;
+    using Microsoft.CodeAnalysis.CSharp;
+    using Microsoft.CodeAnalysis.CSharp.Syntax;
+    using Microsoft.CodeAnalysis.Diagnostics;
+
+    [DiagnosticAnalyzer(LanguageNames.CSharp)]
+    public class PlaceholderDocumentationAnalyzer : DiagnosticAnalyzer
+    {
+        public const string DiagnosticId = "PlaceholderDocumentation";
+        internal const string Title = "Do not use placeholders in documentation";
+        internal const string MessageFormat = "Do not use placeholders in documentation";
+        internal const string Category = "OpenStack.Documentation";
+        internal const string Description = "Do not use placeholders in documentation";
+
+        private static DiagnosticDescriptor Descriptor =
+            new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, isEnabledByDefault: true, description: Description);
+
+        private static readonly ImmutableArray<DiagnosticDescriptor> _supportedDiagnostics =
+            ImmutableArray.Create(Descriptor);
+
+        public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics
+        {
+            get
+            {
+                return _supportedDiagnostics;
+            }
+        }
+
+        public override void Initialize(AnalysisContext context)
+        {
+            context.RegisterSyntaxNodeAction(HandleXmlElement, SyntaxKind.XmlElement);
+            context.RegisterSyntaxNodeAction(HandleXmlEmptyElement, SyntaxKind.XmlEmptyElement);
+        }
+
+        private void HandleXmlElement(SyntaxNodeAnalysisContext context)
+        {
+            XmlElementSyntax syntax = (XmlElementSyntax)context.Node;
+            if (!string.Equals("placeholder", syntax.StartTag?.Name?.ToString(), StringComparison.Ordinal))
+                return;
+
+            context.ReportDiagnostic(Diagnostic.Create(Descriptor, syntax.GetLocation()));
+        }
+
+        private void HandleXmlEmptyElement(SyntaxNodeAnalysisContext context)
+        {
+            XmlEmptyElementSyntax syntax = (XmlEmptyElementSyntax)context.Node;
+            if (!string.Equals("placeholder", syntax.Name?.ToString(), StringComparison.Ordinal))
+                return;
+
+            context.ReportDiagnostic(Diagnostic.Create(Descriptor, syntax.GetLocation()));
+        }
+    }
+}

OpenStackNetAnalyzers/OpenStackNetAnalyzers/PlaceholderDocumentationCodeFix.cs

@@ -0,0 +1,82 @@
+namespace OpenStackNetAnalyzers
+{
+    using System;
+    using System.Collections.Immutable;
+    using System.Composition;
+    using System.Threading;
+    using System.Threading.Tasks;
+    using Microsoft.CodeAnalysis;
+    using Microsoft.CodeAnalysis.CodeActions;
+    using Microsoft.CodeAnalysis.CodeFixes;
+    using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+    [ExportCodeFixProvider(nameof(PlaceholderDocumentationCodeFix), LanguageNames.CSharp)]
+    [Shared]
+    public class PlaceholderDocumentationCodeFix : CodeFixProvider
+    {
+        private static readonly ImmutableArray<string> _fixableDiagnostics =
+            ImmutableArray.Create(PlaceholderDocumentationAnalyzer.DiagnosticId);
+
+        public sealed override ImmutableArray<string> GetFixableDiagnosticIds()
+        {
+            return _fixableDiagnostics;
+        }
+
+        public override FixAllProvider GetFixAllProvider()
+        {
+            // Require users review each removal of placeholder tags.
+            return null;
+        }
+
+        public override async Task ComputeFixesAsync(CodeFixContext context)
+        {
+            foreach (var diagnostic in context.Diagnostics)
+            {
+                if (!string.Equals(diagnostic.Id, PlaceholderDocumentationAnalyzer.DiagnosticId, StringComparison.Ordinal))
+                    continue;
+
+                var documentRoot = await context.Document.GetSyntaxRootAsync(context.CancellationToken);
+                SyntaxNode syntax = documentRoot.FindNode(diagnostic.Location.SourceSpan, findInsideTrivia: true, getInnermostNodeForTie: true);
+                if (syntax == null)
+                    continue;
+
+                XmlElementSyntax xmlElementSyntax = syntax as XmlElementSyntax;
+                if (xmlElementSyntax == null)
+                {
+                    // We continue even for placeholders if they are empty elements (XmlEmptyElementSyntax)
+                    continue;
+                }
+
+                if (string.IsNullOrWhiteSpace(xmlElementSyntax.Content.ToString()))
+                {
+                    // The placeholder hasn't been updated yet.
+                    continue;
+                }
+
+                string description = "Finalize placeholder text";
+                context.RegisterFix(CodeAction.Create(description, cancellationToken => CreateChangedDocument(context, xmlElementSyntax, cancellationToken)), diagnostic);
+            }
+        }
+
+        private async Task<Document> CreateChangedDocument(CodeFixContext context, XmlElementSyntax elementSyntax, CancellationToken cancellationToken)
+        {
+            SyntaxList<XmlNodeSyntax> content = elementSyntax.Content;
+            if (content.Count == 0)
+                return context.Document;
+
+            var leadingTrivia = elementSyntax.StartTag.GetLeadingTrivia();
+            leadingTrivia = leadingTrivia.AddRange(elementSyntax.EndTag.GetTrailingTrivia());
+            leadingTrivia = leadingTrivia.AddRange(content[0].GetLeadingTrivia());
+            content = content.Replace(content[0], content[0].WithLeadingTrivia(leadingTrivia));
+
+            var trailingTrivia = content[content.Count - 1].GetTrailingTrivia();
+            trailingTrivia = trailingTrivia.AddRange(elementSyntax.EndTag.GetLeadingTrivia());
+            trailingTrivia = trailingTrivia.AddRange(elementSyntax.EndTag.GetTrailingTrivia());
+            content = content.Replace(content[content.Count - 1], content[content.Count - 1].WithTrailingTrivia(trailingTrivia));
+
+            SyntaxNode root = await context.Document.GetSyntaxRootAsync(cancellationToken);
+            SyntaxNode newRoot = root.ReplaceNode(elementSyntax, content);
+            return context.Document.WithSyntaxRoot(newRoot);
+        }
+    }
+}