Creating documentation in C# using Visual Studio and Sandcastle
Imagine that you are creating an awesome application, let’s say for example for Windows Phone, but you didn’t pay so much attention to the initial documentation of your project, I mean, not very complete UML diagrams, no proper documentation on the entities definition or just, it’s a very short project where documentation is trivial but at least you want to make sure that if anyone wants to continue with this project, you will provide a proper documentation for the hand over.
Generated static printed documents no long work in an era when technology changes many times a year.
- API documents has been replaced by IntelliSense and Go To Definition
- Designs can be documented by XML comments better than Word documents.
- Books were replaced by Blogs and search engines
An easy way to create your own documentation with an elegant style (see CHM help documents from Microsoft documentation) is through the documentation options in Visual Studio + a great tool to export your code comments and documentation into a readable format.
Let’s split this into two parts.
1) Document your code
In Visual C# you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example.
/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass{}
When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as Sandcastle.
Another example:
/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
/// <summary>
/// Store for the name property.</summary>
private string _name = null;
/// <summary>
/// The class constructor. </summary>
public TestClass()
{
// TODO: Add Constructor Logic here.
}
}
Now, that you now how to comment your code properly, you have to enable one option on the compiler.
Go to the Project Properties –> Build –> Output section –> Enable XML documentation file. See here:
After that build the project and get the generated XML file for the second step.
2) Generate a proper documentation
Now is time to generate a readable documentation through the XML file generated, for that SandCastle is our hero.
If you want to pull all the IntelliSense information out into HTML or compiled Html Help, your going to need some help. Microsoft has Sand Castle to build those documents.
Let’s see what you need to create these CHM files:
- Download and Install Sand Castle via the MSI.
- Download and Install the Sand Castle Help File Builder (SHFB) MSI by Eric Woodruff
- Download and Install / Patch the Sand Castle Styles
- Run SHFB
- Add documentation sources (csproj or dll)
- Add references (csproj or dll)
- Set the help file format and other SHFB options (I recommend using the MemberName naming method to get html links with names instead of Guids)
- Run SHFB build, wait and done!
So, once you have Sand Castle Help File Builder GUI installed, you just have to add the references to the DLL and the references to the XML previously generated file and build the solution
It will take time to get the final build but it worths it :)
- May the code be with you -
References:
SandCastle Help File Builder: https://shfb.codeplex.com/
SandCastle: https://sandcastle.codeplex.com/
XML Documentation Comments: https://msdn.microsoft.com/en-us/library/b2s063f7.aspx
https://tim-stanley.com/post/msdn-style-class-documentation/