Updated documentation and links

sharwell · sharwell · commit b2ed777354a6 · 2015-12-30T16:59:45.000-06:00
diff --git a/AsyncUsageAnalyzers.sln b/AsyncUsageAnalyzers.sln
@@ -28,6 +28,14 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{11D3EB88
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AsyncUsageAnalyzers.CodeFixes", "AsyncUsageAnalyzers\AsyncUsageAnalyzers.CodeFixes\AsyncUsageAnalyzers.CodeFixes.csproj", "{BA0CD420-1E79-4FBC-B023-09C03BCDFFAC}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "documentation", "documentation", "{9E388950-B857-4C92-9429-676FE26BF115}"
+	ProjectSection(SolutionItems) = preProject
+		documentation\AvoidAsyncSuffix.md = documentation\AvoidAsyncSuffix.md
+		documentation\AvoidAsyncVoid.md = documentation\AvoidAsyncVoid.md
+		documentation\UseAsyncSuffix.md = documentation\UseAsyncSuffix.md
+		documentation\UseConfigureAwait.md = documentation\UseConfigureAwait.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
diff --git a/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Naming/AvoidAsyncSuffixAnalyzer.cs b/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Naming/AvoidAsyncSuffixAnalyzer.cs
@@ -22,7 +22,7 @@ internal class AvoidAsyncSuffixAnalyzer : DiagnosticAnalyzer
         private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(NamingResources.AvoidAsyncSuffixMessageFormat), NamingResources.ResourceManager, typeof(NamingResources));
         private static readonly string Category = "AsyncUsage.CSharp.Naming";
         private static readonly LocalizableString Description = new LocalizableResourceString(nameof(NamingResources.AvoidAsyncSuffixDescription), NamingResources.ResourceManager, typeof(NamingResources));
-        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers";
+        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers/blob/master/documentation/AvoidAsyncSuffix.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
diff --git a/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Naming/UseAsyncSuffixAnalyzer.cs b/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Naming/UseAsyncSuffixAnalyzer.cs
@@ -22,7 +22,7 @@ internal class UseAsyncSuffixAnalyzer : DiagnosticAnalyzer
         private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(NamingResources.UseAsyncSuffixMessageFormat), NamingResources.ResourceManager, typeof(NamingResources));
         private static readonly string Category = "AsyncUsage.CSharp.Naming";
         private static readonly LocalizableString Description = new LocalizableResourceString(nameof(NamingResources.UseAsyncSuffixDescription), NamingResources.ResourceManager, typeof(NamingResources));
-        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers";
+        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers/blob/master/documentation/UseAsyncSuffix.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
diff --git a/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Reliability/AvoidAsyncVoidAnalyzer.cs b/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Reliability/AvoidAsyncVoidAnalyzer.cs
@@ -24,7 +24,7 @@ internal class AvoidAsyncVoidAnalyzer : DiagnosticAnalyzer
         private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(ReliabilityResources.AvoidAsyncVoidMessageFormat), ReliabilityResources.ResourceManager, typeof(ReliabilityResources));
         private static readonly string Category = "AsyncUsage.CSharp.Reliability";
         private static readonly LocalizableString Description = new LocalizableResourceString(nameof(ReliabilityResources.AvoidAsyncVoidDescription), ReliabilityResources.ResourceManager, typeof(ReliabilityResources));
-        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers";
+        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers/blob/master/documentation/AvoidAsyncVoid.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
diff --git a/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Usage/UseConfigureAwaitAnalyzer.cs b/AsyncUsageAnalyzers/AsyncUsageAnalyzers/Usage/UseConfigureAwaitAnalyzer.cs
@@ -24,7 +24,7 @@ internal class UseConfigureAwaitAnalyzer : DiagnosticAnalyzer
         private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(UsageResources.UseConfigureAwaitMessageFormat), UsageResources.ResourceManager, typeof(UsageResources));
         private static readonly string Category = "AsyncUsage.CSharp.Usage";
         private static readonly LocalizableString Description = new LocalizableResourceString(nameof(UsageResources.UseConfigureAwaitDescription), UsageResources.ResourceManager, typeof(UsageResources));
-        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers";
+        private static readonly string HelpLink = "https://github.com/DotNetAnalyzers/AsyncUsageAnalyzers/blob/master/documentation/UseConfigureAwait.md";
 
         private static readonly DiagnosticDescriptor Descriptor =
             new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, Category, DiagnosticSeverity.Hidden, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
diff --git a/documentation/AvoidAsyncSuffix.md b/documentation/AvoidAsyncSuffix.md
@@ -0,0 +1,41 @@
+﻿## AvoidAsyncSuffix
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>AvoidAsyncSuffix</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>AvoidAsyncSuffix</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Naming Rules</td>
+</tr>
+</table>
+
+## Cause
+
+A non-Task-returning method is named with the suffix `Async`.
+
+## Rule description
+
+This diagnostic identifies methods which are not asynchronous according to the Task-based Asynchronous Pattern (TAP) by
+their signature, and reports a warning if the method name includes the suffix `Async`.
+
+## How to fix violations
+
+To fix a violation of this rule, remove the `Async` suffix from the method name or change the signature to return a
+`Task`.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable AvoidAsyncSuffix // Avoid Async suffix
+public int ThisIsNotAsync()
+#pragma warning restore AvoidAsyncSuffix // Avoid Async suffix
+{
+    return 0;
+}
+```
diff --git a/documentation/AvoidAsyncVoid.md b/documentation/AvoidAsyncVoid.md
@@ -0,0 +1,38 @@
+﻿## AvoidAsyncVoid
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>AvoidAsyncVoid</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>AvoidAsyncVoid</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Reliability Rules</td>
+</tr>
+</table>
+
+## Cause
+
+An asynchronous method has the return type `void`.
+
+## Rule description
+
+This diagnostic identifies code using `void`-returning `async` methods, and reports a warning.
+
+## How to fix violations
+
+To fix a violation of this rule, change the signature of the method to return a `Task` instead of `void`.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable AvoidAsyncVoid // Avoid async void
+private async void HandleSomeEvent(object sender, EventArgs e)
+#pragma warning restore AvoidAsyncVoid // Avoid async void
+{
+}
+```
diff --git a/documentation/UseAsyncSuffix.md b/documentation/UseAsyncSuffix.md
@@ -0,0 +1,40 @@
+﻿## UseAsyncSuffix
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>UseAsyncSuffix</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>UseAsyncSuffix</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Naming Rules</td>
+</tr>
+</table>
+
+## Cause
+
+A Task-returning method is named without the suffix `Async`.
+
+## Rule description
+
+This diagnostic identifies methods which are asynchronous according to the Task-based Asynchronous Pattern (TAP) by
+their signature, and reports a warning if the method name does not include the suffix `Async`.
+
+## How to fix violations
+
+To fix a violation of this rule, rename the method to include the `Async` suffix.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable UseAsyncSuffix // Use Async suffix
+public async Task<int> GetValue()
+#pragma warning restore UseAsyncSuffix // Use Async suffix
+{
+    return 0;
+}
+```
diff --git a/documentation/UseConfigureAwait.md b/documentation/UseConfigureAwait.md
@@ -0,0 +1,38 @@
+﻿## UseConfigureAwait
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>UseConfigureAwait</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>UseConfigureAwait</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Usage Rules</td>
+</tr>
+</table>
+
+## Cause
+
+A `Task` whose continuation behavior has not been configured is awaited.
+
+## Rule description
+
+The continuation behavior for a `Task` should be configured by calling `ConfigureAwait` prior to awaiting the task. This
+diagnostic is reported if an `await` expression is used on a `Task` that has not been configured.
+
+## How to fix violations
+
+To fix a violation of this rule, use `ConfigureAwait(false)` or `ConfigureAwait(true)` as appropriate for the context of
+the asynchronous operation.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable UseConfigureAwait // Use ConfigureAwait
+await Task.Delay(1000);
+#pragma warning restore UseConfigureAwait // Use ConfigureAwait
+```
