- Creating Web Components in Angular - February 23, 2021
- What is your Communication Style? - August 1, 2020
- Sharing is caring? - January 28, 2020
Stuck with creating tedious documentation for your .NET projects? Sandcastle, a documentation tool from Microsoft is here to save you! This amazing tool will help you create MSDN style clean and useful documents. All you need to do is make some simple changes to your .NET code and voila – your project documentation will be ready in no time!
Step 1 : Installing Sandcastle.
You can download Sandcastle from here.
Use the sandcastleInstaller to install as below:
During installation it will ask if you want to install the visual studio package, so that you can use Sandcastle directly from Visual Studio. In this tutorial I won’t be covering how to use the visual studio extension package. This tutorial scope is limited only to document creation directly from Sandcastle GUI. You can skip installing this extension if you want to.
Once the installation is complete, check if you can see the Sandcastle GUI symbol in the installed programs.
Click on the GUI icon. If you see an error like below, install the MS Build Tools to fix this.
Once you have installed the MS Build Tools, you should be able to open the Sandcastle GUI without any issues.
Now for demo purposes let’s create a class library in Visual Studio.
Step 2 : Creating a demo project
Creating a project
We will first create a simple class library and add an Employee class. For demo purposes, we will be adding private member variables, properties and methods to this class.
This class has two properties id and Name. It also has a getName method. The important component to add here are the XML comments . Sandcastle utilizes these comments to create documentation.
Creating an XML file.
To proceed with the documentation we will also need to create an XML file for the project. To do so, right click on the project, select properties, then in the Build tab, check the XML documentation file option. Note the path where the XML document will be created.
If we navigate to the XML path, we will see that an XML file will be created as below:
This file is not in a very readable format. Sandcastle helps us create a document in a much more readable style.
Using SandCastle Help File Builder
Now open the SandCastle Help File Builder tool and create a new project. Let’s name it ‘SandCastleDemo’. On the right hand side, you will find an option to add Documentation Source. Right click on it and add your XML file to it.
Before we proceed with documentation creation, let’s explore a few options in the Project Properties tab on the left.
In the build section, check the Website format, as we will be documenting an ASP.NET web-site.
The Help File section will provide you options regarding copyrights, footers etc.
The Help1/Website options gives you choice to include MSDN help topics
The MS Help 2 and MS Help Viewer will give you options to include further details regarding the document.
In the Summaries section you can add summaries for your namespace.
In the Visibility section you will find all the elements that you would want to include in your documentation.
The Missing Tags section will give you an option whether you want to include documentation regarding the missing elements like Dispose methods etc, if they are not present in the code.
The Paths section will include the path where the document will be created. You can change it from here. Take a note of this path, as our document will be created here.
There are additional options present, which can be used to change our documentation preferences.
Once we are done setting our preferences, build the file, using the following icon.
Once the build is successful, we will get the corresponding message in the Build Output tab.
Once the build is successful, navigate to the path where the help documentation was created. This can be found out from the Paths section in the Project properties tab as discussed above. In the help folder you will find an index.html file. Open it to view your documentation.
Clicking on the Employee class, you will find all the documentation related to its constructors, method, properties etc.
You will find the code translated in different programming languages (eg. VB, C++) like the MSDN Help documents. These preferences can of course be changed.
It will also include information about the methods that were not explicitly included in the code.
Step 3 : Fixing Errors.
If some information in the document is missing, SandCastle highlights it in red. For eg, if in the XML comments for the method getName, we remove the bordered information as shown in the below image, SandCastle will highlight it for us.
Now when we create the document in SandCastle we will get an error as follows:
Such pointers help us know the information that the project comments are missing.
This brings an end to my brief intro on how to use SandCastle GUI to create documentation for your .NET projects. Please let me know if you have any questions.