Creating a Simple Documentation Builder Tool

Application Documentation allows the developer to quickly get in pace with the project. Documentation also allows the new developers to quickly understand the system. One of the tools that was widely used to create documentation was NDoc. Unfortunately, NDoc is not supported anymore. Another tool was SandCastle but it was taken offline due to some open source challenges. Although both the tools mentioned above created professional looking documentaion we can always create a simple tool that will generate the basic documentation for an application.

Introduction:

Creating the XML Documentation File:

The XML Documentation file is automatically created using Visual Studio by setting some build properties. The XML file contains the elements that define the documentation for a project. Take a look at the screen shot below which shows how to enable the XML documentation on a project.

Once, the XML Documentation is enabled for the project and the project is build. The XML file will be created automatically and will be placed in the directory specified by the user.

Let’s take a look at a simple Customer.cs class file which contains some XML comments which will be ported to the XML documentation file. Customer class is part of the DocumentationDemo class library project.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace DocumentationDemo
{
    /// <summary>
    /// This is the customer class!
    /// </summary>
    public class Customer
    {

       /// <summary>
       /// This is the GetCustomer Method
       /// </summary>
       /// <param name="id">The id of the customer</param>
       /// <returns>The customer object</returns>
        public static Customer GetCustomer(int id)
        {
            return null;
        }

       /// <summary>
       /// This is the AddCustomer method
       /// </summary>
       /// <param name="customer">Customer entity</param>
       /// <returns>returns the identity value for the customer</returns>
        public static int AddCustomer(Customer customer)
        {
            return 1;
        }

        /// <summary>
        /// This is the Delete Customer method
        /// </summary>
        /// <param name="customer">Customer Entity</param>
        public static void DeleteCustomer(Customer customer)
        {
            // deletes the customer
        }

}

As, you can see above the class name and methods are decorated with XML comments. All these XML comments are ported to the automatically generated XML file.

Let’s take a look at the auto-generated XML documentation file:

Now, we need a way to make the above XML file look pretty and readable by the users.

Using XSL to Make XML File Readable:

XSL stands for Extensible Stylesheet Language and is used to style up the XML documents. Let’s check out some of the basic functions of the XSLT file which helps to transform the XML document.

The above XSLT will extract and display the assembly name from the XML file.

We also need to display the class name to the user. The class name is represented by the letter T in the XML file. Take a look at the following Type contained in the XML documentation file.

<member name="T:DocumentationDemo.Customer">
            <summary>
            This is the customer class!
            </summary>
        </member>

We need to display the class name but without the prefix “T:” Here is the XSLT to perform that:

                  </xsl:if>
                </h4>

              </div>

We used the substring function to extract the correct class name.

There are lots of other functions, loops and conditional statements inside the XSLT file which you can view by downloading the complete project at the bottom of this article.

Creating a Windows Interface:

Let’s create a very simple windows application that will generate the readable documentation file. Take a look at the screenshot below which shows the interface for this application:

First, the user must select the XML documentation file which is automatically created when the application is build. The second file is the XSLT file which contains all the transformation code for the XML file. Finally, the user must indicate where the documentation will be saved. The documentation is saved as a HTML file which can be opened in any web browser.

Let’s take a look at the transformation code:

private void button3_Click(object sender, EventArgs e)
{
// generate documentation

            string outputDir = textBox3.Text;
            string xmlCommentsFilePath = textBox1.Text;
            string xsltFilePath = textBox2.Text;
            string documentationFileName = String.Format("{0}{1}", outputDir, "Documentation.html");

            XPathDocument doc = new XPathDocument(xmlCommentsFilePath);

XslTransform xsl = new XslTransform();
xsl.Load(xsltFilePath);

            if (!Directory.Exists(textBox3.Text))
            {
                Directory.CreateDirectory(textBox3.Text);
            }

            FileStream fs = File.Create(documentationFileName);


            XmlTextWriter xtw = new XmlTextWriter(fs, null);
            xsl.Transform(doc, null, xtw);
            xtw.Close();
            fs.Close();

}

The transformation code simply applies the XSLT transformation on an XML file and uses the FileStream object to create the HTML documentation file.

Here is the output generated by the application:

Conclusion:

In this article we learned how to style the XML documentation file and use XSLT transformation to create a simple looking documentation. If you are looking to create MSDN style documentation then check out the SandCastle project.

I hope you liked the article, happy programming!

[Download Project]