Fix additional documentation items found when reviewing SA1629 violations

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.CodeFixes/OrderingRules/UsingCodeFixProvider.SourceMap.cs

@@ -18,11 +18,16 @@ internal sealed partial class UsingCodeFixProvider
     {
         /// <summary>
         /// Contains a map of the different regions of a source file.
-        /// Used source file regions are:
-        /// - conditional directives (#if, #else, #elif, #endif)
-        /// - pragma warning directives
-        /// - region directives.
         /// </summary>
+        /// <remarks>
+        /// <para>Used source file regions are:</para>
+        ///
+        /// <list type="bullet">
+        /// <item>conditional directives (#if, #else, #elif, #endif)</item>
+        /// <item>pragma warning directives</item>
+        /// <item>region directives</item>
+        /// </list>
+        /// </remarks>
         private class SourceMap
         {
             private readonly TreeTextSpan regionRoot;

StyleCop.Analyzers/StyleCop.Analyzers.Status.Generator/SolutionReader.cs

@@ -62,10 +62,10 @@ private SolutionReader()
         /// <summary>
         /// Creates a new instance of the <see cref="SolutionReader"/> class.
         /// </summary>
-        /// <param name="pathToSln">The path to the StyleCop.Analayzers sln.</param>
+        /// <param name="pathToSln">The path to the StyleCop.Analayzers solution.</param>
         /// <param name="analyzerProjectName">The project name of the analyzer project.</param>
         /// <param name="codeFixProjectName">The project name of the code fix project.</param>
-        /// <returns>A <see cref="Task{SolutionReader}"/> representing the asynchronous operation.</returns>
+        /// <returns>A <see cref="Task{TResult}"/> representing the asynchronous operation.</returns>
         public static async Task<SolutionReader> CreateAsync(string pathToSln, string analyzerProjectName = "StyleCop.Analyzers", string codeFixProjectName = "StyleCop.Analyzers.CodeFixes")
         {
             SolutionReader reader = new SolutionReader();

StyleCop.Analyzers/StyleCop.Analyzers.Status.Generator/StyleCopDiagnostic.cs

@@ -97,7 +97,7 @@ public class StyleCopDiagnostic
         /// Creates an instance of the <see cref="StyleCopDiagnostic"/> class
         /// that is populated with the data stored in <paramref name="value"/>.
         /// </summary>
-        /// <param name="value">A json representing a <see cref="StyleCopDiagnostic"/>.</param>
+        /// <param name="value">A JSON string representing a <see cref="StyleCopDiagnostic"/>.</param>
         /// <returns>A <see cref="StyleCopDiagnostic"/> that is populated with the data stored in <paramref name="value"/>.</returns>
         public static StyleCopDiagnostic FromJson(string value)
         {
@@ -116,9 +116,9 @@ public override string ToString()
         }
 
         /// <summary>
-        /// Returns a json representation of this diagnostic.
+        /// Returns a JSON representation of this diagnostic.
         /// </summary>
-        /// <returns>A json string representing this diagnostic.</returns>
+        /// <returns>A JSON string representing this diagnostic.</returns>
         public string ToJson()
         {
             return JsonConvert.SerializeObject(this);

StyleCop.Analyzers/StyleCop.Analyzers.Test/HelperTests/IndentationHelperTests.cs

@@ -99,7 +99,7 @@ public class IndentationHelperTests
         private const string TestFilename = "Test0.cs";
 
         /// <summary>
-        /// Verify the workings of IndentationHelper.GetIndentationSteps.
+        /// Verify the workings of <see cref="IndentationHelper.GetIndentationSteps(IndentationSettings, SyntaxToken)"/>.
         /// </summary>
         /// <param name="indentationString">The indentation string to use with the test.</param>
         /// <param name="expectedIndentationSteps">The expected number of indentation steps.</param>
@@ -121,7 +121,8 @@ public async Task VerifyGetIndentationStepsAsync(string indentationString, int e
         }
 
         /// <summary>
-        /// Verify the that IndentationHelper.GetIndentationSteps will return zero (0) for tokens that are not the first token on a line.
+        /// Verify the that <see cref="IndentationHelper.GetIndentationSteps(IndentationSettings, SyntaxToken)"/> will
+        /// return zero (0) for tokens that are not the first token on a line.
         /// </summary>
         /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
         [Fact]

StyleCop.Analyzers/StyleCop.Analyzers.Test/Helpers/DiagnosticVerifier.Helper.cs

@@ -251,7 +251,7 @@ protected DiagnosticResult CSharpCompilerError(string errorIdentifier)
         /// <param name="sources">Classes in the form of strings.</param>
         /// <param name="language">The language the source classes are in. Values may be taken from the
         /// <see cref="LanguageNames"/> class.</param>
-        /// <param name="filenames">The filenames or null if the default filename should be used.</param>
+        /// <param name="filenames">The filenames or <see langword="null"/> if the default filename should be used.</param>
         /// <returns>A <see cref="Project"/> created out of the <see cref="Document"/>s created from the source
         /// strings.</returns>
         protected Project CreateProject(string[] sources, string language = LanguageNames.CSharp, string[] filenames = null)
@@ -266,7 +266,7 @@ protected Project CreateProject(string[] sources, string language = LanguageName
         /// <param name="sources">Classes in the form of strings.</param>
         /// <param name="language">The language the source classes are in. Values may be taken from the
         /// <see cref="LanguageNames"/> class.</param>
-        /// <param name="filenames">The filenames or null if the default filename should be used.</param>
+        /// <param name="filenames">The filenames or <see langword="null"/> if the default filename should be used.</param>
         /// <returns>A <see cref="Project"/> created out of the <see cref="Document"/>s created from the source
         /// strings.</returns>
         protected virtual Project CreateProjectImpl(string[] sources, string language, string[] filenames)
@@ -296,7 +296,7 @@ protected virtual Project CreateProjectImpl(string[] sources, string language, s
         /// <remarks>
         /// <para>The default implementation configures the project by enabling all supported diagnostics of analyzers
         /// included in <see cref="GetCSharpDiagnosticAnalyzers"/> as well as <c>AD0001</c>. After configuring these
-        /// diagnostics, any diagnostic IDs indicated in <see cref="GetDisabledDiagnostics"/> are explictly supressed
+        /// diagnostics, any diagnostic IDs indicated in <see cref="GetDisabledDiagnostics"/> are explicitly suppressed
         /// using <see cref="ReportDiagnostic.Suppress"/>.</para>
         /// </remarks>
         /// <param name="project">The project.</param>
@@ -381,7 +381,7 @@ private static Diagnostic[] SortDistinctDiagnostics(IEnumerable<Diagnostic> diag
         /// <see cref="LanguageNames"/> class.</param>
         /// <param name="analyzers">The analyzers to be run on the sources.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> that the task will observe.</param>
-        /// <param name="filenames">The filenames or null if the default filename should be used.</param>
+        /// <param name="filenames">The filenames or <see langword="null"/> if the default filename should be used.</param>
         /// <returns>A collection of <see cref="Diagnostic"/>s that surfaced in the source code, sorted by
         /// <see cref="Diagnostic.Location"/>.</returns>
         private Task<ImmutableArray<Diagnostic>> GetSortedDiagnosticsAsync(string[] sources, string language, ImmutableArray<DiagnosticAnalyzer> analyzers, CancellationToken cancellationToken, string[] filenames)
@@ -396,7 +396,7 @@ private Task<ImmutableArray<Diagnostic>> GetSortedDiagnosticsAsync(string[] sour
         /// <param name="sources">Classes in the form of strings.</param>
         /// <param name="language">The language the source classes are in. Values may be taken from the
         /// <see cref="LanguageNames"/> class.</param>
-        /// <param name="filenames">The filenames or null if the default filename should be used.</param>
+        /// <param name="filenames">The filenames or <see langword="null"/> if the default filename should be used.</param>
         /// <returns>A collection of <see cref="Document"/>s representing the sources.</returns>
         private Document[] GetDocuments(string[] sources, string language, string[] filenames)
         {

StyleCop.Analyzers/StyleCop.Analyzers.Test/WorkItemAttribute.cs

@@ -6,7 +6,7 @@ namespace StyleCop.Analyzers.Test
     using System;
 
     /// <summary>
-    /// Used to tag test methods or types which are created for a given WorkItem.
+    /// Used to tag test methods or types which are created for a given work item.
     /// </summary>
     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
     public sealed class WorkItemAttribute : Attribute

StyleCop.Analyzers/StyleCop.Analyzers/Helpers/XmlCommentHelper.cs

@@ -54,7 +54,7 @@ internal static class XmlCommentHelper
         /// - it is null
         /// - it does not have any text in any XML element and it does not have an empty XML element in it.
         /// </summary>
-        /// <param name="xmlComment">The xmlComment that should be checked.</param>
+        /// <param name="xmlComment">The XML comment that should be checked.</param>
         /// <returns>true, if the comment should be considered empty, false otherwise.</returns>
         internal static bool IsConsideredEmpty(DocumentationCommentTriviaSyntax xmlComment)
         {
@@ -78,7 +78,7 @@ internal static bool IsConsideredEmpty(DocumentationCommentTriviaSyntax xmlComme
         /// This helper is used by documentation diagnostics to check if a XML comment should be considered empty.
         /// A comment is empty if it does not have any text in any XML element and it does not have an empty XML element in it.
         /// </summary>
-        /// <param name="xmlSyntax">The xmlSyntax that should be checked.</param>
+        /// <param name="xmlSyntax">The XML syntax that should be checked.</param>
         /// <param name="considerEmptyElements">Flag indicating if empty elements should be considered or assumed non-empty.</param>
         /// <returns>true, if the comment should be considered empty, false otherwise.</returns>
         internal static bool IsConsideredEmpty(XmlNodeSyntax xmlSyntax, bool considerEmptyElements = false)
@@ -171,10 +171,14 @@ internal static bool IsConsideredEmpty(XNode node)
         }
 
         /// <summary>
-        /// Checks if a SyntaxTrivia contains a DocumentationCommentTriviaSyntax and returns true if it is considered empty.
+        /// Checks if a <see cref="SyntaxTrivia"/> contains a <see cref="DocumentationCommentTriviaSyntax"/> and returns
+        /// <see langword="true"/> if it is considered empty.
         /// </summary>
-        /// <param name="commentTrivia">A SyntaxTrivia containing possible documentation.</param>
-        /// <returns>true if commentTrivia does not have documentation in it or the documentation in SyntaxTriviais considered empty. False otherwise.</returns>
+        /// <param name="commentTrivia">A <see cref="SyntaxTrivia"/> containing possible documentation.</param>
+        /// <returns>
+        /// <see langword="true"/> if <paramref name="commentTrivia"/> does not have documentation in it or the
+        /// documentation in <paramref name="commentTrivia"/> is considered empty; otherwise, <see langword="false"/>.
+        /// </returns>
         internal static bool IsMissingOrEmpty(SyntaxTrivia commentTrivia)
         {
             if (!commentTrivia.HasStructure)

StyleCop.Analyzers/StyleCop.Analyzers/LightJson/JsonValue.cs

@@ -487,8 +487,8 @@ public JsonValue this[string key]
         /// Gets or sets the value at the specified index.
         /// </summary>
         /// <param name="index">The zero-based index of the value to get or set.</param>
-        /// <exception cref="System.InvalidOperationException">
-        /// Thrown when this JsonValue is not a JsonArray.
+        /// <exception cref="InvalidOperationException">
+        /// Thrown when this <see cref="JsonValue"/> is not a <see cref="JsonArray"/>.
         /// </exception>
         public JsonValue this[int index]
         {