Improve documentation of MA0004

meziantou · Jan 23, 2024 · 21e8a55 · 21e8a55
1 parent 2a94244
commit 21e8a55
Show file tree

Hide file tree

Showing 4 changed files with 12 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ If you are already using other analyzers, you can check [which rules are duplica
 |[MA0001](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0001.md)|Usage|StringComparison is missing|ℹ️|✔️|✔️|
 |[MA0002](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0002.md)|Usage|IEqualityComparer\<string\> or IComparer\<string\> is missing|⚠️|✔️|✔️|
 |[MA0003](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0003.md)|Style|Add parameter name to improve readability|ℹ️|✔️|✔️|
-|[MA0004](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0004.md)|Usage|Use Task.ConfigureAwait(false)|⚠️|✔️|✔️|
+|[MA0004](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0004.md)|Usage|Use Task.ConfigureAwait|⚠️|✔️|✔️|
 |[MA0005](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0005.md)|Performance|Use Array.Empty\<T\>()|⚠️|✔️|✔️|
 |[MA0006](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0006.md)|Usage|Use String.Equals instead of equality operator|⚠️|✔️|✔️|
 |[MA0007](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0007.md)|Style|Add a comma after the last value|ℹ️|✔️|✔️|

diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@
 |[MA0001](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0001.md)|Usage|StringComparison is missing|<span title='Info'>ℹ️</span>|✔️|✔️|
 |[MA0002](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0002.md)|Usage|IEqualityComparer\<string\> or IComparer\<string\> is missing|<span title='Warning'>⚠️</span>|✔️|✔️|
 |[MA0003](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0003.md)|Style|Add parameter name to improve readability|<span title='Info'>ℹ️</span>|✔️|✔️|
-|[MA0004](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0004.md)|Usage|Use Task.ConfigureAwait(false)|<span title='Warning'>⚠️</span>|✔️|✔️|
+|[MA0004](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0004.md)|Usage|Use Task.ConfigureAwait|<span title='Warning'>⚠️</span>|✔️|✔️|
 |[MA0005](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0005.md)|Performance|Use Array.Empty\<T\>()|<span title='Warning'>⚠️</span>|✔️|✔️|
 |[MA0006](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0006.md)|Usage|Use String.Equals instead of equality operator|<span title='Warning'>⚠️</span>|✔️|✔️|
 |[MA0007](https://github.com/meziantou/Meziantou.Analyzer/blob/main/docs/Rules/MA0007.md)|Style|Add a comma after the last value|<span title='Info'>ℹ️</span>|✔️|✔️|
@@ -172,7 +172,7 @@ dotnet_diagnostic.MA0002.severity = warning
 # MA0003: Add parameter name to improve readability
 dotnet_diagnostic.MA0003.severity = suggestion
 
-# MA0004: Use Task.ConfigureAwait(false)
+# MA0004: Use Task.ConfigureAwait
 dotnet_diagnostic.MA0004.severity = warning
 
 # MA0005: Use Array.Empty<T>()
@@ -632,7 +632,7 @@ dotnet_diagnostic.MA0002.severity = none
 # MA0003: Add parameter name to improve readability
 dotnet_diagnostic.MA0003.severity = none
 
-# MA0004: Use Task.ConfigureAwait(false)
+# MA0004: Use Task.ConfigureAwait
 dotnet_diagnostic.MA0004.severity = none
 
 # MA0005: Use Array.Empty<T>()

diff --git a/docs/Rules/MA0004.md b/docs/Rules/MA0004.md
@@ -1,15 +1,18 @@
-# MA0004 - Use Task.ConfigureAwait(false)
+# MA0004 - Use Task.ConfigureAwait
 
-You should use `ConfigureAwait(false)` except when you really need to use the current `SynchronizationContext`, such as in a WinForm, WPF or ASP.NET context.
+- If the `SynchronizationContext` is not needed, you should use `ConfigureAwait(false)`
+- If the `SynchronizationContext` is needed (WinForm, WPF, ASP.NET, Blazor, etc.), you can use `ConfigureAwait(true)` or `ConfigureAwait(ConfigureAwaitOptions.ContinueOnCapturedContext)` to make it explicit, or you can disable the rule locally
 
 ````csharp
 await task;
 
 // Should be
 await task.ConfigureAwait(false);
+// or
+await task.ConfigureAwait(true);
 ````
 
-Configuration (`.editorconfig`)
+## Configuration (`.editorconfig`)
 
 ````
 [.*cs]

diff --git a/src/Meziantou.Analyzer/Rules/UseConfigureAwaitAnalyzer.cs b/src/Meziantou.Analyzer/Rules/UseConfigureAwaitAnalyzer.cs
@@ -16,8 +16,8 @@ public sealed class UseConfigureAwaitAnalyzer : DiagnosticAnalyzer
 {
     private static readonly DiagnosticDescriptor Rule = new(
         RuleIdentifiers.UseConfigureAwaitFalse,
-        title: "Use Task.ConfigureAwait(false)",
-        messageFormat: "Use Task.ConfigureAwait(false) as the current SynchronizationContext is not needed",
+        title: "Use Task.ConfigureAwait",
+        messageFormat: "Use Task.ConfigureAwait(false) if the current SynchronizationContext is not needed",
         RuleCategories.Usage,
         DiagnosticSeverity.Warning,
         isEnabledByDefault: true,