RCS1140 - Don't require user to document exception types if caught in…

… same method (#1524)

ChangeLog.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fix analyzer [RCS1202](https://josefpihrt.github.io/docs/roslynator/analyzers/RCS1202) ([PR](https://github.com/dotnet/roslynator/pull/1542))
 - Fix analyzer [RCS1246](https://josefpihrt.github.io/docs/roslynator/analyzers/RCS1246) ([PR](https://github.com/dotnet/roslynator/pull/1543))
+- Fix analyzer [RCS1140](https://josefpihrt.github.io/docs/roslynator/analyzers/RCS1140) ([PR](https://github.com/dotnet/roslynator/pull/1524))
 
 ## [4.12.6] - 2024-09-23
 

src/Common/CSharp/Analysis/AddExceptionToDocumentationComment/AddExceptionToDocumentationCommentAnalysis.cs

@@ -61,6 +61,9 @@ private static AddExceptionToDocumentationCommentAnalysisResult Analyze(
  if (!InheritsFromException(typeSymbol, exceptionSymbol))
  return Fail;
 
+ if (IsExceptionTypeCaughtInMethod(node, typeSymbol, semanticModel, cancellationToken))
+ return Fail;
+
  ISymbol declarationSymbol = GetDeclarationSymbol(node.SpanStart, semanticModel, cancellationToken);
 
  if (declarationSymbol?.GetSyntax(cancellationToken) is not MemberDeclarationSyntax containingMember)
@@ -216,4 +219,32 @@ private static bool InheritsFromException(ITypeSymbol typeSymbol, INamedTypeSymb
  && typeSymbol.BaseType?.IsObject() == false
  && typeSymbol.InheritsFrom(exceptionSymbol);
  }
+
+ /// <summary>
+ /// Walk upwards from throw statement and find all try statements in method and see if any of them catches the thrown exception type
+ /// </summary>
+ private static bool IsExceptionTypeCaughtInMethod(SyntaxNode node, ITypeSymbol exceptionSymbol, SemanticModel semanticModel, CancellationToken cancellationToken)
+ {
+ SyntaxNode parent = node.Parent;
+ while (parent is not null)
+ {
+ if (parent is TryStatementSyntax tryStatement && tryStatement.Catches.Any(catchClause => SymbolEqualityComparer.Default.Equals(exceptionSymbol, semanticModel.GetTypeSymbol(catchClause.Declaration?.Type, cancellationToken))))
+ {
+ return true;
+ }
+
+ if (parent is MemberDeclarationSyntax or LocalFunctionStatementSyntax)
+ {
+ // We don't care if it's caught outside of the current method
+ // Since the exception should be documented in this method
+ return false;
+ }
+ else
+ {
+ parent = parent.Parent;
+ }
+ }
+
+ return false;
+ }
 }

src/Tests/Analyzers.Tests/RCS1140AddExceptionToDocumentationCommentTests.cs

@@ -0,0 +1,154 @@
+// Copyright (c) .NET Foundation and Contributors. Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.Threading.Tasks;
+using Microsoft.CodeAnalysis;
+using Roslynator.CSharp.CodeFixes;
+using Roslynator.Testing.CSharp;
+using Xunit;
+
+namespace Roslynator.CSharp.Analysis.Tests;
+
+public class RCS1140AddExceptionToDocumentationCommentTests : AbstractCSharpDiagnosticVerifier<AddExceptionToDocumentationCommentAnalyzer, AddExceptionToDocumentationCommentCodeFixProvider>
+{
+ public override DiagnosticDescriptor Descriptor { get; } = DiagnosticRules.AddExceptionToDocumentationComment;
+
+ [Fact, Trait(Traits.Analyzer, DiagnosticIdentifiers.AddExceptionToDocumentationComment)]
+ public async Task Test_Example_From_Documentation()
+ {
+ await VerifyDiagnosticAndFixAsync("""
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ public void Foo(object parameter)
+ {
+ if (parameter == null)
+ [|throw new ArgumentNullException(nameof(parameter));|]
+ }
+}
+
+""", """
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ /// <exception cref="ArgumentNullException"><paramref name="parameter"/> is <c>null</c>.</exception>
+ public void Foo(object parameter)
+ {
+ if (parameter == null)
+ throw new ArgumentNullException(nameof(parameter));
+ }
+}
+
+""");
+ }
+
+ [Fact, Trait(Traits.Analyzer, DiagnosticIdentifiers.AddExceptionToDocumentationComment)]
+ public async Task Test_No_Diagnostic_If_Exception_Is_Caught_In_Method()
+ {
+ await VerifyNoDiagnosticAsync("""
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ public void Foo(object parameter)
+ {
+ try 
+ {
+ if (parameter == null)
+ throw new ArgumentNullException(nameof(parameter));
+ }
+ catch (ArgumentNullException) {}
+ }
+}
+""");
+ }
+
+ [Fact, Trait(Traits.Analyzer, DiagnosticIdentifiers.AddExceptionToDocumentationComment)]
+ public async Task Test_No_Diagnostic_If_Exception_Is_Caught_In_Method_Nested()
+ {
+ await VerifyNoDiagnosticAsync("""
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ public void Foo(object parameter)
+ {
+ try 
+ {
+ try 
+ {
+ if (parameter == null)
+ throw new ArgumentNullException(nameof(parameter));
+ }
+ catch (InvalidOperationException) {}
+ }
+ catch (ArgumentNullException) {}
+ }
+}
+""");
+ }
+
+ [Fact, Trait(Traits.Analyzer, DiagnosticIdentifiers.AddExceptionToDocumentationComment)]
+ public async Task Test_Diagnostic_If_Not_Correct_Exception_Is_Caught_In_Method()
+ {
+ await VerifyDiagnosticAndFixAsync("""
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ public void Foo(object parameter)
+ {
+ try 
+ {
+ if (parameter == null)
+ [|throw new ArgumentNullException(nameof(parameter));|]
+ }
+ catch (InvalidOperationException) {}
+ }
+}
+
+""", """
+using System;
+
+class C
+{
+ /// <summary>
+ /// ...
+ /// </summary>
+ /// <param name="parameter"></param>
+ /// <exception cref="ArgumentNullException"><paramref name="parameter"/> is <c>null</c>.</exception>
+ public void Foo(object parameter)
+ {
+ try 
+ {
+ if (parameter == null)
+ throw new ArgumentNullException(nameof(parameter));
+ }
+ catch (InvalidOperationException) {}
+ }
+}
+
+""");
+ }
+}