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
- 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.
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.
- Renamed XML Comment Checker (no longer Visual Basic specific).
- Added extensive checks for use with both C# and VB.
- Checks are configurable.
- Fixed issue with ByRef and array parameter types.
- First release: then named Visual Basic 2005 XML Comment Checker.