GOTCHA 19 Naming XML documentation for IntelliSense support isn t intuitive

GOTCHA #19 Naming XML documentation for IntelliSense support isn't intuitive

Writing XML-style documentation is supported in C# out of the box. Third-party tools can be used to generate XML documentation for VB.NET code. The next version of Visual Basic (Visual Basic 2005, which is also known as the Whidbey release) will support XML comments directly. There are two advantages to writing this documentation. One, it serves to specify what your code does, without regard to how it does it. This can be useful for users of your APIboth internal users and external users. Second, it provides IntelliSense when your classes are used.

However, the XML document must have the same name as your assembly and must have the .xml extension. When an assembly is referenced in a project, Visual Studio brings over not only the assembly, but also the related XML documentation file. If it is named something other than the exact name of the assembly, this process does not happen and IntelliSense does not provide the details of your classes, methods, properties, etc.

As mentioned, the usefulness of the XML documentation goes beyond IntelliSense. Open source tools like NDoc (See the section "On the Web" in the Appendix) may be used to produce MSDN-like or HTML documentation. Figure 2-18 shows an example of what NDoc produces.

Figure 2-19 shows how you can configure the C# project settings to generate the XML document. Given that the XML documentation file name should be the same as the assembly name, a checkbox instead of a textbox for XML Documentation File would have been appropriate.

IN A NUTSHELL

Name the XML documentation file the same as your assembly name to ensure that IntelliSense will work properly.

Figure 2-18. Documentation produced using NDoc

Figure 2-19. C# project settings to generate XML documentation

SEE ALSO

Gotcha #18, "Creating Web apps can be painful."