PH2124.md

PH2124: Document unhandled exceptions

Property	Value
Package	Philips.CodeAnalysis.MaintainabilityAnalyzers
Diagnostic ID	PH2124
Category	Documentation
Analyzer	DocumentUnhandledExceptionsAnalyzer
CodeFix	Yes
Severity	Error
Enabled By Default	Yes

Introduction

Be clear about the possible behaviors of your code to its users, including bad weather scenarios. This includes documenting the complete list of possible exceptions that might occur.

Please note that any exception that is caught does not have to be documented, as its existence is not known to your caller.

How to solve

Any exception that can occur as a result of calling your method, should be mentioned in the method's XML documentation. There is a special exception element for this. Use this element to describe the conditions in which this exception can occur.

Example

Code that triggers a diagnostic:

using System.IO;
public class BadExample {
  /// <summary>Some description</summary>
  public void BadCode() {
    Directory.Create("abc");
  }
}

And the replacement code:

using System.IO;
public class GoodExample {
  /// <summary>Some description</summary>
  /// <exception cref="IOException">The condition in which this exception can occur</exception>
  public void GoodCode() {
    Directory.Create("abc");
  }
}

Configuration

This analyzer does not offer any special configuration. The general ways of suppressing diagnostics apply.

Similar Analyzers

See these analyzers for other rules related to exceptions:

ID	Title
PH2120	Document thrown exceptions
PH2121	Throw informational exceptions
PH2122	Avoid Exceptions from unexpected locations
PH2124	Document unhandled exceptions