SlashDocs is a Visual Studio Add-In to help to write and maintain C# XML Comment Documentation in external files included using the C# Documentation Comment <include tag. This is a specialized tool for my needs, but may be useful to other class library developers managing C# XML documentation in an external file.
To use SlashDocs right-clicking on a type (e.g. class, struct, interface, enum) or member (e.g. method, property, event), and Select Open SlashDoc File from the menu.
Right-click on a method and select Open Slash Doc File to get the Add-In to change documentation comments in the source code from this:
/// <summary>
/// Invokes my method.
/// </summary>
/// <param name="myParam">This is my param.</param>
public void MyMethod(object myParam)
{
}
...to this:
/// <include file="SlashDocs\MyClass.slashdoc" path="/Libraries/Types/Type[@name="MyClass"]/Members/Member[@name="MyMethod"]/Docs"/>
public void MyMethod(object myParam)
{
}
...and this (in a separate file):
<?xml version="1.0" encoding="utf-8"?>
<Libraries>
<Types>
<Type name="MyClass">
<Members>
<Member name="MyMethod">
<Docs>
<summary>
Invokes my method.
</summary>
<param name="myParam">This is my param.</param>
</Docs>
</Member>
</Members>
</Type>
</Types>
</Libraries>
The SlashDocs Add-In makes moving documentation from the source code to C# XML Comment documentation in an external file quick and easy. It also will quickly jump to the documentation in an external file, if the include statement already exists.
After selecting the Open SlashDoc File item from the context menu, a dialog appears so you can preview path and file name of the external "slashdoc" file that is used when you press OK.A screenshot of this dialog is below:
The dialog in the screenshot is pretty daunting at first, but if you have ever managed these <include...> tags before, it should make sense
quickly. I'll try to explain what everything is for. SlashDocs generates the name and path of the target slashdoc file based on the source code file's name and path. To do so it uses two regular expressions: A Match Expression and a Replace Expression, which are the first two fields under Project Settings.
The Match Expression is used to grab the interesting information from the source code file's name and path. Typically, the portion of the path relative to some root directory, and the name of the source code file.
The Replace Expression is used to "replace" the portions of the source code file's path with the changes necessary to generate the target path and filename of the target slashdoc file.
The next textbox under project settings which is labeled File Include Base Path is used to generate the path used in the file attribute of the include tag ("SlashDocs\MyClass.slashdoc" in the first example above). This is the path that the value of the file attribute in the include tag is relative to. This must be the directory where the csc.exe compiler is invoked from. Typically this is the solution directory, but I believe with VS2005 this changed to the project directory. When using nant or command line access to csc.exe, obviously you have more control. Whatever your need is, that path should provide enough flexibility. As noted in the dialog, these are saved with the project, so once you get them right for your project, you shouldn't need to change them again. Hopefully you'll just push OK and jump to the file.
March 5, 2006: Get the latest update here.
So download the installer
here (166kb), and post any comments or questions you have.
posted @ Tuesday, November 29, 2005 4:53 AM