.NET 1.1+

Documenting Exceptions

by Richard Carr, published at http://www.blackwasp.co.uk/DocumentingExceptions.aspx

Code can be decorated with XML documentation comments, which can be compiled into documentation files. When members can throw exceptions, the comments can include a description of each expected exception and the reasons why it may be thrown.

XML Comments

XML documentation comments can be added to types and their members using the special comment symbol of three forward slashes (///). If Visual Studio is configured to do so, the three slashes are automatically expanded and XML elements are added for the item being described. For example, a method may automatically be decorated with placeholders for a summary of the method, a description of each parameter and details of the return value.

The automatically inserted XML elements of a documentation comment are not exhaustive. There are a number of other elements that may be added to enhance the final documentation. One of the additional XML elements is exception. A number of exception elements may be added to the comments for a method, property, event or indexer. Each specifies a type of exception that the member may be expected to throw and a description, usually the reason why it will occur. It is a good idea to add expected exception details to your documentation, particularly when writing reusable library code.

The exception element requires an attribute named, "cref". The value of the attribute should be set to the name of the exception. The description that you wish to link to it should be placed between the starting and ending exception tags. If you reference a custom exception that is declared within your code and you compile the XML documentation into a HTML Help file using Sandcastle, the exception name will be created as an internal link to the documentation for the exception type. If you specify a standard .NET framework exception, the text will link to the online MSDN documentation.

The following code shows a method signature with some documentation comments. The last comment describes the reason why a System.ArgumentNullException may be thrown.

/// <summary>
/// Moves the robot in a specified manner.
/// </summary>
/// <param name="movement">The manner in which to move the robot</param>
/// <exception cref="System.ArgumentNullException">Thrown if no movement data is provided.
/// </exception>
public void Move(MovementData movement)