Merge pull request #2008 from sharwell/port-1957

Port #1957 to stabilization

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/DocumentationRules/PropertySummaryDocumentationCodeFixProvider.cs

@@ -40,12 +40,15 @@ public override Task RegisterCodeFixesAsync(CodeFixContext context)
         {
             foreach (Diagnostic diagnostic in context.Diagnostics)
             {
-                context.RegisterCodeFix(
-                    CodeAction.Create(
-                        DocumentationResources.PropertySummaryStartTextCodeFix,
-                        cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
-                        nameof(PropertySummaryDocumentationCodeFixProvider)),
-                    diagnostic);
+                if (!diagnostic.Properties.ContainsKey(PropertySummaryDocumentationAnalyzer.NoCodeFixKey))
+                {
+                    context.RegisterCodeFix(
+                        CodeAction.Create(
+                            DocumentationResources.PropertySummaryStartTextCodeFix,
+                            cancellationToken => GetTransformedDocumentAsync(context.Document, diagnostic, cancellationToken),
+                            nameof(PropertySummaryDocumentationCodeFixProvider)),
+                        diagnostic);
+                }
             }
 
             return SpecializedTasks.CompletedTask;
@@ -59,14 +62,18 @@ private static async Task<Document> GetTransformedDocumentAsync(Document documen
             var documentation = node.GetDocumentationCommentTriviaSyntax();
 
             var summaryElement = (XmlElementSyntax)documentation.Content.GetFirstXmlElement(XmlCommentHelper.SummaryXmlTag);
-            var textElement = (XmlTextSyntax)summaryElement.Content.First();
+            var textElement = (XmlTextSyntax)summaryElement.Content.FirstOrDefault();
+            if (textElement == null)
+            {
+                return document;
+            }
+
             var textToken = textElement.TextTokens.First(token => token.IsKind(SyntaxKind.XmlTextLiteralToken));
             var text = textToken.ValueText;
-            var newTextBuilder = StringBuilderPool.Allocate();
 
             // preserve leading whitespace
             int index = 0;
-            while (char.IsWhiteSpace(text, index))
+            while (text.Length > index && char.IsWhiteSpace(text, index))
             {
                 index++;
             }
@@ -85,14 +92,18 @@ private static async Task<Document> GetTransformedDocumentAsync(Document documen
                 modifiedText = text.Substring(index);
             }
 
-            modifiedText = char.ToLowerInvariant(modifiedText[0]) + modifiedText.Substring(1);
+            if (modifiedText.Length > 0)
+            {
+                modifiedText = char.ToLowerInvariant(modifiedText[0]) + modifiedText.Substring(1);
+            }
 
             // create the new text string
             var textToAdd = diagnostic.Properties[PropertySummaryDocumentationAnalyzer.ExpectedTextKey];
             var newText = $"{preservedWhitespace}{textToAdd} {modifiedText}";
 
             // replace the token
-            var newTextTokens = textElement.TextTokens.Replace(textToken, SyntaxFactory.XmlTextLiteral(textToken.LeadingTrivia, newText, newText, textToken.TrailingTrivia));
+            var newXmlTextLiteral = SyntaxFactory.XmlTextLiteral(textToken.LeadingTrivia, newText, newText, textToken.TrailingTrivia);
+            var newTextTokens = textElement.TextTokens.Replace(textToken, newXmlTextLiteral);
             var newTextElement = textElement.WithTextTokens(newTextTokens);
 
             var newSyntaxRoot = syntaxRoot.ReplaceNode(textElement, newTextElement);

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1623UnitTests.cs

@@ -152,6 +152,30 @@ private class PrivateTestClass
             await this.VerifyCSharpFixAsync(testCode, fixedTestCode).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Verifies that empty summary tag does not throw an exception.
+        /// Regression test for #1943
+        /// </summary>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Fact]
+        public async Task EmptySummaryTagShouldNotThrowAnExceptionAsync()
+        {
+            var testCode = @"public class ClassName
+{
+    /// <summary></summary>
+    public int Property
+    {
+        get;
+    }
+}";
+
+            var expected = this.CSharpDiagnostic(PropertySummaryDocumentationAnalyzer.SA1623Descriptor).WithLocation(4, 16).WithArguments("Gets");
+            await this.VerifyCSharpDiagnosticAsync(testCode, expected, CancellationToken.None).ConfigureAwait(false);
+
+            var offeredFixes = await this.GetOfferedCSharpFixesAsync(testCode).ConfigureAwait(false);
+            Assert.Empty(offeredFixes);
+        }
+
         /// <inheritdoc/>
         protected override CodeFixProvider GetCSharpCodeFixProvider()
         {

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/PropertySummaryDocumentationAnalyzer.cs

@@ -19,6 +19,7 @@ internal class PropertySummaryDocumentationAnalyzer : PropertyDocumentationBase
     {
         public const string ExpectedTextKey = "ExpectedText";
         public const string TextToRemoveKey = "TextToRemove";
+        public const string NoCodeFixKey = "NoCodeFix";
 
         private const string SA1623DiagnosticId = "SA1623";
         private const string SA1624DiagnosticId = "SA1624";
@@ -108,6 +109,13 @@ private static void AnalyzeSummaryElement(SyntaxNodeAnalysisContext context, Xml
                 return;
             }
 
+            // Add a no code fix tag when the summary element is empty.
+            // This will only impact SA1623, because SA1624 cannot trigger with an empty summary.
+            if (summaryElement.Content.Count == 0)
+            {
+                diagnosticProperties.Add(NoCodeFixKey, string.Empty);
+            }
+
             var textElement = summaryElement.Content.FirstOrDefault() as XmlTextSyntax;
             var text = textElement == null ? string.Empty : XmlCommentHelper.GetText(textElement, true).TrimStart();