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 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 a 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 is 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 helps 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 two or four years later, you may “still” have the idea of 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 commenton 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 todo you 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 two years, you lose the focus that you had back in those days when you started the project. This happens to me too.

calm
Figure 1: Keep calm, programmers!

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 times 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 of 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 a part 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 the run-time. In the IDE, we know what the class name is, and what the functionsare that are 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 the 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 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 will end this section with this one code sample:

  1. class Student
  2. {
  3. publicint ID
  4. {
  5. get;
  6. set;
  7. }
  8. public string Name
  9. {
  10. get;
  11. set;
  12. }
  13. }
  15. // In the main function
  16. public static void Main(string[] args)
  17. {
  18. var type = typeof(Student);
  20. // Above line is similar to,
  21. var type = new Student().GetType();
  23. // But prefer the previous one.
  25. // We can use the variable to extract the name of the type.
  26. Console.WriteLine(type.Name);
  27. }
  29. // 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 MSDN, System.Reflection Namespace.

Building the HTML document

As I have already mentioned that you can use ASP.NET web site, web application tool, 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 that 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:
  1. <!doctype html>
  2. <html>
  4. <head>
  5. <title></title>
  6. <style>
  7. html
  8. {
  9. margin: 0 auto;
  10. font-family: 'Segoe UI';
  11. font-size: 13px;
  12. }
  14. body
  15. {
  16. /* Nothing special here. */
  17. }
  19. table
  20. {
  21. min-width: 500px;
  22. border: 1px dashed #cecece;
  23. padding: 5px 10px;
  24. text-align: center;
  25. }
  27. tabletr:first-child
  28. {
  29. width: 150px;
  30. font-size: 15px;
  31. font-weight: 600px;
  32. }
  33. </style>
  34. </head>
  36. <body>
  37. <h4></h4>
  38. <p></p>
  39. <table id="properties">
  41. </table>
  42. <table id="methods">
  44. </table>
  45. </body>
  47. </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.

If you consider using C# 6, you will be provided with useful features such as, string interpolation etc.
  1. // Create the instance
  2. StringBuilder builder = new StringBuilder();
  4. // Append html head
  5. builder.AppendLine("<!doctype html><html><head>");
  7. // Append title and the style here
  8. // Append the lines, based on an iterative loop
  10. // Append the final lines
  11. builder.AppendLine("</body></html>");
  13. // Get the document
  14. varhtmlDoc = 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 of contents or anything, but just the simple title and the full name of the object. Whose web page screenshot is:

content
Figure 2: Rendering the dynamic HTML content.

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 those documentations 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.

Read more articles on C# Programming: