Building a Custom Documentation Tool

Introduction and Background

A team of software developers would all be willing to write a great amount of documentation because after all, it is the document that provides their users a resource from where they can get some help. But if your team believes in Agile development methodologies, then you are better off left with programming and “no-documentation” face! That is not at all a problem to most of the programmers, but that is also not a good practice after all. Most of the libraries and tools out there require a good documentation of their APIs. This can be understood by the fact that many programmers are building applications for Microsoft platforms and not for other platforms. I consider myself one of them. The fact is easy, to get any kind of help in Microsoft platforms, I just need to go to MSDN (Microsoft Developer Network) and I can get any document, help with any framework, with any object, with any task and much more. Microsoft has really invested a lot of their time in building a great amount of resources on the internet. Their investment pays off in a way that others cannot expect to get paid. The result is, they get a lot of attention from developers, and novice programmers also feel great while programming. Compare this to that of Linux, compare this to that of any Java library and so on. I don’t want to be biased, but Java APIs, even of Oracle, are very badly written. There is a list of functions, but no remarks, no explanation, no nothing, which makes it much more complex for beginners to learn and get a grasp of.

Currently, I am seeking my Master’s degree in Computer Science and I am going to have a project to build later this year. While that has some months to come, I am thinking of something to build that would help me in many ways. One of them is to build a custom program that will help me to document the API so that I can submit that to the professors when they ask me for my project.

This blog post is about the “things” I have thought about, while building the tool. I haven’t built the tool yet, but I am hoping to have it built soon. But, I can show you the blueprint and the scratch code for that.

Why Document the Code?

If you are an indie developer, and you don’t like to share the code with anyone, don’t worry about this. Chances are that 2 or 4 years later, you may “still” have the idea, why you wrote down that code. But if you also have to share the same code with your partner, team or external world, then, you should either comment the code well. But… in the cases, where you don’t want to share the internal code, then you should provide a well written API for that code.

That would save you from many messages, emails and feedback like, “How to do that?”. That question annoys many people because, the developer of that API is already aware of the “simplicity” of the API, but others don’t know it. They are not aware of the objects introduced and so on. In such cases, you should always consider documenting the code well, so that others, when facing a problem, can simply read that documentation and say, “Oh, that’s how I do that!”

In many cases, it also helps you when after 2 years, you lose the focus that you had back in those days when you started the project. Happens to me too. :-)

How to Build a Custom Documentation Tool?

I am sorry to disappoint you guys, but I am going to talk about C# only. There was a lot of time when I was learning other frameworks, writing applications for Linux, compiling articles and books for other operating systems. This is, when I feel I need to get back to where I belong. I belong to C#. I am going to use C# to show you how you can build the application that documents the code that you have written. Now that is somewhat a complex idea and process. But, for the sake of this post, I am going to keep things really very short here and I will demonstrate the use of the very basic concepts to build such a great and vital tool for your team so that they can focus more on the programming part, and leave the documentation part to this tool itself.

I am going to use the following three basic features:

1. C# language itself
   • You can use any framework, Console, WPF, WinForms, etc.
2. HTML document for previewing the results
   • You may use ASP.NET applications or web sites for previewing. I used static HTML pages.
3. Some reflection
   • In the above parts, I think most of you would get yourselves confused when it comes to “Reflection” in C#. Well, it is not that tough to understand. Reflection in C# (or .NET itself) is a very simple and easy concept to understand. Using reflection, we can simply get to know the assemblies, objects, classes and their members, on run-time. In the IDE, we know what is the class name, what are functions defined. But how to know on run-time, is a part of reflection.

Introduction to Reflection

Before I finally end up the post, I want to give you an overview of reflection in C#. If you have ever programmed in C#, you are aware of typeof() operator or GetType() function. Both of them are the first steps toward reflection. Basically, reflection is performed on types of the objects. Types expose the assembly information, members information, properties, functions (methods) and events information… Much more! So, we use the signature to determine many values, like the names, assembly, namespace, versioning, etc.

I am going to use the same tool, and I am going to extract the properties from these types and I am going to build an HTML documentation for the classes. This is the same mechanism which is used on MSDN or any other “good” documentation. You should never write the documentation yourself, one object after the other. Create an interface which does the underlying task and then do the modifications and reviews.

I would end this section with this one code sample:

class Student {
   public int ID { get; set; }
   public string Name { get; set; }
}

// In the main function
public static void Main(string[] args) {
    var type = typeof(Student);

    // Above line is similar to, 
    var type = new Student().GetType();

    // But prefer the previous one. 

    // We can use the variable to extract the name of the type.
    Console.WriteLine(type.Name);
}

// Output: Student

We get many other similar functions that we may use to actually get the information on the class that we are using.

You should try them out, for further reading, please refer to MSDN: System.Reflection Namespace.

Building the HTML Document

As I have already mentioned, you can use ASP.NET web site, web application too, to represent the documentation for online users. But I used static HTML pages, which are much simpler to build and don’t have to manage the rest of the underlying stuff for the application.

What I did was I used a C# program to render the HTML content for me. Based on the type that I pass, I created a new class, “DocumentHelper”, and created a function which takes an object and renders the HTML document for its name. Here is what I made:

<!doctype html>
<html>
<head>
   <title></title>
   <style>
      html {
         margin: 0 auto;
         font-family: 'Segoe UI';
         font-size: 13px;
      }
 
      body {
         /* Nothing special here. */
      }

      table {
         min-width: 500px;
         border: 1px dashed #cecece;
         padding: 5px 10px;
         text-align: center;
      }

      table tr:first-child {
         width: 150px;
         font-size: 15px;
         font-weight: 600;
      }
   </style>
</head>
<body>
   <h4></h4>
   <p></p>
   <table id="properties">
 
   </table>
   <table id="methods">
 
   </table>
</body>
</html>

This is the very basic HTML document that will be used to render the details for the item. We can then use the C# program to loop over the properties and render them in our HTML document. This is just the template, obviously when being used, the HTML document "must" be updated and classes and IDs must be added to the elements for better control over the document.

If you would consider using C# 6, you would be provided with useful features such as, string interpolation, etc.

// Create the instance
StringBuilder builder = new StringBuilder();

// Append html head
builder.AppendLine("<!doctype html><html><head>");

// Append title and the style here
// Append the lines, based on an iterative loop

// Append the final lines
builder.AppendLine("</body></html>");

// Get the document
var htmlDoc = builder.ToString();

You can then store the file, and at the same time, execute the call to show the file too.

System.Diagnostics.Process.Start(linkToFile);

It would open the default application to render the HTML file (if you saved the file with .html or .html extension). In my case, it was Google Chrome. I did not write the table content or anything, but just the simple title and the full name of the object whose web page screenshot is:

This way, we can use other classes and their types to render the documentation web pages too.

Points of Interest

In this post, I have talked about the simplest method required to build a tool that automatically documents the code in your project. You can share the HTML documents with your clients who can easily read the documentation based on the content that you have provided based on the UI you use in the HTML document.

Of course, this is not complete. This was just the idea that I was having and I am hoping to complete this project as soon as possible and if I do develop, I will share the source code publicly on GitHub.

There are many more things to do:

1. Learn Reflection
2. Find a good way to store the HTML documents:
   • In database
   • In static files
   • Other data source
3. Build a crawler for your API

Crawler would simply crawl from one object to another using the relations and would continue to build the documentation. :-)