XML Comment Checker is an application that will check the XML documentation for a .Net assembly for omissions. It offers a more comprehensive checking than the C# compiler itself, and is ideal for when you wish to check your comments before compiling them into real documentation, e.g using Microsoft Sandcastle.

Like the C# compiler, XML Comment Checker will check whether all publicly visible types and members (i.e. public types and public or protected members) have XML comments. It can be used to perform this check for Visual Basic code, as the Visual Basic compiler does not provide these checks.

Additionally, XML Comment checker offers the following features not offered by either the C# or VB compilers (note: XML Comment Checker was developed for .Net 2.0; this list may not be accurate for later versions of the compilers):

• Check for required sections. You can ensure sections such as <summary> or <remarks> are present. Which sections are required can be configured per member type by altering the CommentChecker.exe.config file. By default, XML Comment Checker will check for the <summary> and <threadsafety> sections on classes and structures, the <summary> and <value> sections on properties, and the <summary> section for everything else. See the CommentChecker.exe.config file for more details.
• Check for the presence of <typeparam> and <param> elements. XML Comment checker will check whether all parameters of methods and all type parameters of generic types or methods are documented.
• Check for the presence of <returns> elements. XML Comment Checker will warn if a method with a non-void return type does not have a <returns> element.
• Check for empty sections. Optionally, XML Comment Checker will warn if any of the required sections or elements are present, but empty. This is not enabled by default
• Check for exceptions. XML Comment Checker will check for exception types used in a method body and will warn if they have no matching <exception> element. Note that exception checking is limited: only the current method will be checked, not any methods called from that method. It also scans only for instantiations of classes deriving from Exception; it does not check whether they are actually thrown.
• Check for language words. Sandcastle allows for certain keywords to appear in <see langword="" /> elements. It will then make sure they are displayed correctly based on the current documentation language. XML Comment checker will check whether any of these keywords appear in plain text (i.e. not in a <see> element) and warn if this is the case. Keyword supported currently are null (Nothing in Visual Basic), true, false, virtual (Overridable in Visual Basic) and static (Shared in Visual Basic). Language words can be configured using the CommentChecker.exe.config file.
• Configurable checks. All checks can be disabled using command line parameters, in addition to the configurability with the CommentChecker.exe.config file.
• Use either VB or C# syntax for type and member names in the printed warnings.

Usage

Stand alone

XML Comment checker is a command line application. For full usage information, see the readme.txt file included in the download, or run it without parameters.

From Visual Studio

XML Comment Checker can be set as the post-build event in Visual Studio to check an assembly automatically. The warnings emitted by XML Comment Checker have been formatted so that Visual Studio will recognize them and display them in the Error List. An example post-build command line:
"PathToCommentChecker\CommentChecker.exe" "$(TargetPath)" -nologo -warnemptysections

You may need to set the post-build event to run "When the build updates the project output" to avoid "file not found" errors.

The post-build event can be found on a separate tab (Build Events) on the properties of a C# project, or by using the "Build Events" button at the bottom of the Compile tab for a VB project.

Version history

Version 2.0

• Renamed XML Comment Checker (no longer Visual Basic specific).
• Added extensive checks for use with both C# and VB.
• Checks are configurable.

Version 1.1

• Fixed issue with ByRef and array parameter types.

Version 1.0

• First release: then named Visual Basic 2005 XML Comment Checker.