The CR_Documentor plug-in allows you to view XML comments as rendered comments right inside of the IDE.
XML comments in C# and Visual Basic 2005 enable developers to create clear documentation of software classes. Keeping the XML comments right in the source helps mitigate documentation disconnects when a developer changes something in existing code – at least if they change the comments as they’re updating the code.
These XML comments can be extracted out to a separate XML file during the build process by selecting a project’s property pages and checking the “XML Documentation File” option on the “Build” tab. By default the resulting XML file lands in the build’s output directory.
This XML file can then be used to create any number of separate help files including Windows Help (chm), HTML help, or MSDN-style help. Developers can use simple XSL transforms or a tool like NDoc to produce the documentation.
However, this requires a separate build step which can be a nuisance when all you’re trying to do is verify you’ve got a <see> reference correct.
Travis Illig has helped out by porting Lutz Roeder’s “Documentor” application into the DXCore framework. This enables developers to see rendered documentation from a window directly within the Visual Studio IDE.
[NOTE: DXCore, from Developer Express, is the framework behind their popular CodeRush productivity booster. DXCore is freely available, but only for personal use.]
Download Illig’s plugin, exit all Visual Studio instances, and drop the dll file into DXCore’s plugin directory (“C:\Program Files\Developer Express Inc\DXCore for Visual Studio .NET\1.1\Bin\Plugins” on my system.) After restarting Visual Studio you’ll see the “Documentor” option under the DevExpress -> Tool Windows menu. A separate dockable window appears in the IDE.
One hitch with the plugin is that text in separate files loaded via the <include> tag aren’t pulled in and rendered; however, text clearly notes this and shows the file location and XPath parameter.
This window renders documentation in HTML format any time you have the cursor in an XML comment. Links via <see> and <seealso> are properly displayed, although inactive, and <code> sections are formatted just as they would be in “real” documentation.
CR_Documentor has a number of useful configuration options available through the Documentor section of the DevExpress -> Options dialog. You can select between MSDN and NDoc’s tag sets, determine how to handle undefined tags, replace tabs in <code> sections with spaces, and toggle the toolbar off and on in the Documentor window.
CR_Documentor is a great little tool: it’s simple and does one thing very well. It’s a very handy add-in if you’re using CodeRush or DXCore.
Travis Illig, creator of the CR_Documentor plugin recently passed on some news about his plugin. He’s updated it to provide support for the <include> tag — the only tag that was previously unsupported. You can find his updated plugin at his blog.
As a side note, Travis said he solved the problem in part by using System.Web.Caching outside of a web context.
