x.doc is a Visual Studio (VS) 2005 add-in that provides a means to manage and visualize source-code comment documentation interactively in the IDE. A screen-shot is shown below:
x.doc provides two windows:
- The Visualizer window which is the window that provides the rendered XML documentation text using a defined set of XSL templates and a CSS. This window is interactively updated as the caret is moved in a code-editor window. If the documentation is not well-formed XML or an error occurs in the rendering, an error is displayed in this window. If the caret is not positioned in a documentation block, the message "No documentation" is displayed. This window is implemented to work as a standard 'Tool Window' in the IDE, and can be floated, docked etc. like any other tool window.
- The Output window which is similar to the IDE build window in that it displays the error with the appropriate source-code file path and line and character position offsets. Double-clicking the error line in this window will move the caret to the referenced editor window and offset in the code at which the error has occurred. It shares the standard output window and its content is displayed by selecting the x.doc menu-item in the 'Show output from:' selector.
x.doc provides a menu tool-strip above the Visualizer window, and is described below as they are ordered on the tool-strip (from left-to-right):
- Prior Documentation Item: This button command moves the caret to the prior documentation block in the code editor window and selects the block as shown in the diagram above.
- Next Documentation Item: This command moves the caret to the next documentation block.
- Collapse All Documentation: This command traverses the entire code document and outlines the documentation blocks. Each documentation block is shown only by three ellipses ('...') and is an effective way to quickly hide all the documentation.
- Import Documentation Item: This button command imports the documentation from an external file and embeds it as a documentation block in the source-code. This will only happen if the caret is positioned over a single-line documentation block containing a well-formed tag that points to a valid external documentation file with a name attribute that can be resolved to a documentation item in the external file.
- Export Documentation Item: This command reverses the action of the 'Import Documentation Item' above. The documentation block is exported to the external documentation file and a suitably formed tag is substituted in its place. (See The Code section for constraints on the use of this tag). Note that badly-formed XML is exported "as-is", so it is best to check the Output window for errors before exporting the documentation block.
- Import All Documentation: This command works the same as the "Import Documentation Item" above, except that it traverses the entire source-code file and imports all documentation.
- Export All Documentation: This command exports all documentation to the external documentation file, reversing the action executed by 'Import All Documentation' above.
- Documentation Display Style Selector: This selection list will accommodate any number of XSL/CSS templates which are imported from external .xsl and .css files when the add-in is first loaded. The XSL/CSS files x.doc.xsl and x.doc.css are included with the x.doc add-in installer and provides a pseudo-MSDN documentation look-and-feel. Obviously, these files can be modified or more style files added, which can then be individually selected, causing the documentation to be immediately re-rendered using the selected style. It is also possible to extend the VS IDE documentation tags and provide customized documentation functionality. NDoc already does this to provide the various standards of documentation-styles, including their MSDN style, which is exactly like the Microsoft H1 and H2 Help.
x.doc is completely NDoc compatible, in that the XML files that are generated by VS when you compile with the /doc:file option can be used as-is with NDoc. This applies whether the documentation is read directly from the source-code, or from an external file.