Merge pull request #1183 from sharwell/add-docs

Initial conversion of HTML to markdown

StyleCop.Analyzers/StyleCop.Analyzers.Test/Helpers/ExclusionTestAnalyzer.cs

@@ -17,9 +17,10 @@ internal class ExclusionTestAnalyzer : DiagnosticAnalyzer
         private const string Title = "Exclusion test";
         private const string MessageFormat = "Exclusion test";
         private const string Description = "Exclusion test";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA9999.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
-            new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, "TestRules", DiagnosticSeverity.Warning, true, Description);
+            new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, "TestRules", DiagnosticSeverity.Warning, true, Description, HelpLink);
 
         private static readonly ImmutableArray<DiagnosticDescriptor> SupportedDiagnosticsValue =
             ImmutableArray.Create(Descriptor);

StyleCop.Analyzers/StyleCop.Analyzers.Test/Verifiers/DiagnosticVerifier.cs

@@ -29,6 +29,29 @@ public async Task TestEmptySourceAsync()
             await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Verifies that each diagnostics contains a <see cref="DiagnosticDescriptor.HelpLinkUri"/> in the expected
+        /// format.
+        /// </summary>
+        [Fact]
+        public void TestHelpLink()
+        {
+            foreach (var diagnosticAnalyzer in this.GetCSharpDiagnosticAnalyzers())
+            {
+                foreach (var diagnostic in diagnosticAnalyzer.SupportedDiagnostics)
+                {
+                    if (diagnostic.DefaultSeverity == DiagnosticSeverity.Hidden && diagnostic.CustomTags.Contains(WellKnownDiagnosticTags.NotConfigurable))
+                    {
+                        // This diagnostic will never appear in the UI.
+                        continue;
+                    }
+
+                    string expected = $"https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/{diagnostic.Id}.md";
+                    Assert.Equal(expected, diagnostic.HelpLinkUri);
+                }
+            }
+        }
+
         /// <summary>
         /// Gets the C# analyzers being tested
         /// </summary>

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1600ElementsMustBeDocumented.cs

@@ -31,7 +31,7 @@ public class SA1600ElementsMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Elements must be documented";
         private const string MessageFormat = "Elements must be documented";
         private const string Description = "A C# code element is missing a documentation header.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1600.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1600.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1601PartialElementsMustBeDocumented.cs

@@ -72,7 +72,7 @@ public class SA1601PartialElementsMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Partial elements must be documented";
         private const string MessageFormat = "Partial elements must be documented";
         private const string Description = "A C# partial element is missing a documentation header.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1601.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1601.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1602EnumerationItemsMustBeDocumented.cs

@@ -43,7 +43,7 @@ public class SA1602EnumerationItemsMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Enumeration items must be documented";
         private const string MessageFormat = "Enumeration items must be documented";
         private const string Description = "An item within a C# enumeration is missing an Xml documentation header.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1602.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1602.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1603DocumentationMustContainValidXml.cs

@@ -32,7 +32,7 @@ public class SA1603DocumentationMustContainValidXml : DiagnosticAnalyzer
         private const string Title = "Documentation must contain valid XML";
         private const string MessageFormat = "The documentation header is composed of invalid XML: {0}";
         private const string Description = "The XML within a C# element’s document header is badly formed.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1603.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1603.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1604ElementDocumentationMustHaveSummary.cs

@@ -28,7 +28,7 @@ public class SA1604ElementDocumentationMustHaveSummary : ElementDocumentationSum
         private const string Title = "Element documentation must have summary";
         private const string MessageFormat = "Element documentation must have summary";
         private const string Description = "The XML header documentation for a C# element is missing a <summary> tag.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1604.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1604.md";
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
 

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1605PartialElementDocumentationMustHaveSummary.cs

@@ -75,7 +75,7 @@ public class SA1605PartialElementDocumentationMustHaveSummary : PartialElementDo
         private const string Title = "Partial element documentation must have summary";
         private const string MessageFormat = "Partial element documentation must have summary";
         private const string Description = "The <summary> or <content> tag within the documentation header for a C# code element is missing or empty.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1605.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1605.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1606ElementDocumentationMustHaveSummaryText.cs

@@ -30,7 +30,7 @@ public class SA1606ElementDocumentationMustHaveSummaryText : ElementDocumentatio
         private const string Title = "Element documentation must have summary text";
         private const string MessageFormat = "Element documentation must have summary text";
         private const string Description = "The <summary> tag within the documentation header for a C# code element is empty.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1606.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1606.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1607PartialElementDocumentationMustHaveSummaryText.cs

@@ -74,7 +74,7 @@ public class SA1607PartialElementDocumentationMustHaveSummaryText : PartialEleme
         private const string Title = "Partial element documentation must have summary text";
         private const string MessageFormat = "Partial element documentation must have summary text";
         private const string Description = "The <summary> or <content> tag within the documentation header for a C# code element is empty.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1607.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1607.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1608ElementDocumentationMustNotHaveDefaultSummary.cs

@@ -37,7 +37,7 @@ public class SA1608ElementDocumentationMustNotHaveDefaultSummary : DiagnosticAna
         private const string Title = "Element documentation must not have default summary";
         private const string MessageFormat = "Element documentation must not have default summary";
         private const string Description = "The <summary> tag within an element's XML header documentation contains the default text generated by Visual Studio during the creation of the element.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1608.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1608.md";
 
         private const string DefaultText = "Summary description for";
 

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1609PropertyDocumentationMustHaveValue.cs

@@ -30,7 +30,7 @@ public class SA1609PropertyDocumentationMustHaveValue : PropertyDocumentationSum
         private const string Title = "Property documentation must have value";
         private const string MessageFormat = "Property documentation must have value";
         private const string Description = "The XML header documentation for a C# property does not contain a <value> tag.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1609.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1609.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.DisabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1610PropertyDocumentationMustHaveValueText.cs

@@ -31,7 +31,7 @@ public class SA1610PropertyDocumentationMustHaveValueText : PropertyDocumentatio
         private const string Title = "Property documentation must have value text";
         private const string MessageFormat = "Property documentation must have value text";
         private const string Description = "The XML header documentation for a C# property contains an empty <value> tag.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1610.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1610.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1611ElementParametersMustBeDocumented.cs

@@ -33,7 +33,7 @@ public class SA1611ElementParametersMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Element parameters must be documented";
         private const string MessageFormat = "The documentation for parameter '{0}' is missing";
         private const string Description = "A C# method, constructor, delegate or indexer element is missing documentation for one or more of its parameters.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1611.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1611.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1612ElementParameterDocumentationMustMatchElementParameters.cs

@@ -33,7 +33,7 @@ public class SA1612ElementParameterDocumentationMustMatchElementParameters : Dia
         public const string DiagnosticId = "SA1612";
         private const string Title = "Element parameter documentation must match element parameters";
         private const string Description = "The documentation describing the parameters to a C# method, constructor, delegate or indexer element does not match the actual parameters on the element.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1612.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1612.md";
 
         private const string MissingParamForDocumentationMessageFormat = "The parameter '{0}' does not exist.";
         private const string ParamWrongOrderMessageFormat = "The parameter documentation for '{0}' should be at position {1}.";

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1613ElementParameterDocumentationMustDeclareParameterName.cs

@@ -32,7 +32,7 @@ public class SA1613ElementParameterDocumentationMustDeclareParameterName : Diagn
         private const string Title = "Element parameter documentation must declare parameter name";
         private const string MessageFormat = "Element parameter documentation must declare parameter name";
         private const string Description = "A <param> tag within a C# element's documentation header is missing a name attribute containing the name of the parameter.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1613.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1613.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1614ElementParameterDocumentationMustHaveText.cs

@@ -32,7 +32,7 @@ public class SA1614ElementParameterDocumentationMustHaveText : DiagnosticAnalyze
         private const string Title = "Element parameter documentation must have text";
         private const string MessageFormat = "Element parameter documentation must have text";
         private const string Description = "A <param> tag within a C# element's documentation header is empty.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1614.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1614.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1615ElementReturnValueMustBeDocumented.cs

@@ -30,7 +30,7 @@ public class SA1615ElementReturnValueMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Element return value must be documented";
         private const string MessageFormat = "Element return value must be documented";
         private const string Description = "A C# element is missing documentation for its return value.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1615.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1615.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1616ElementReturnValueDocumentationMustHaveText.cs

@@ -31,7 +31,7 @@ public class SA1616ElementReturnValueDocumentationMustHaveText : DiagnosticAnaly
         private const string Title = "Element return value documentation must have text";
         private const string MessageFormat = "Element return value documentation must have text";
         private const string Description = "The <returns> tag within a C# element's documentation header is empty.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1616.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1616.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1617VoidReturnValueMustNotBeDocumented.cs

@@ -31,7 +31,7 @@ public class SA1617VoidReturnValueMustNotBeDocumented : DiagnosticAnalyzer
         private const string Title = "Void return value must not be documented";
         private const string MessageFormat = "Void return value must not be documented";
         private const string Description = "A C# code element does not contain a return value, or returns void, but the documentation header for the element contains a <returns> tag.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1617.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1617.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1618GenericTypeParametersMustBeDocumented.cs

@@ -31,7 +31,7 @@ public class SA1618GenericTypeParametersMustBeDocumented : DiagnosticAnalyzer
         private const string Title = "Generic type parameters must be documented";
         private const string MessageFormat = "The documentation for type parameter '{0}' is missing";
         private const string Description = "A generic C# element is missing documentation for one or more of its generic type parameters.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1618.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1618.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);

StyleCop.Analyzers/StyleCop.Analyzers/DocumentationRules/SA1619GenericTypeParametersMustBeDocumentedPartialClass.cs

@@ -81,7 +81,7 @@ public class SA1619GenericTypeParametersMustBeDocumentedPartialClass : Diagnosti
         private const string Title = "Generic type parameters must be documented partial class";
         private const string MessageFormat = "The documentation for type parameter '{0}' is missing";
         private const string Description = "A generic, partial C# element is missing documentation for one or more of its generic type parameters, and the documentation for the element contains a <summary> tag.";
-        private const string HelpLink = "http://www.stylecop.com/docs/SA1619.html";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1619.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.DocumentationRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);