Creating Documentation for your Published Libraries

In the previous article, we published NuGet package on nuget.org. If you are publishing libraries, the value of the code is higher with included API documentation.

XML Documentation Comments

Usually, the problem with API documentations is that they are outdated because they refer to previous versions of the code. For this reason, an API documentation style was invented. Programmers maintain the documentation, just near the documented code piece in comments. With the .NET language family, the structure of the comments is called XML Documentation Comments. The comment blocks are a bit different depending on the language, but only because the comment language feature is different. For example, in C# a comment is started with two slashes (//), while in Visual Basic with the apostrophe (‘) character. In a similar manner, in C# you start the XML documentation comment lines with three slashes (///), while in Visual Basic you start with three apostrophes (”’). The content of the comments is the same.

In his book, Clean Code: A Handbook of Agile Software Craftsmanship, Robert C. Martin states that you should avoid comments in your code, because they indicate that your code is not self-explanatory enough. While this is true for most of your software code, XML Documentation comments are not explaining your code itself, but the APIs you implemented. Having them at the same place as the API itself, allows you to maintain it and provide the information to other programmers, who usually won’t read your code. In such sense, they are your customers, and they only want to use your software library as a product. Beside sparing the time for them to read the code itself, they might not even have the chance to read it, if all they are provided with is the binary. Thus, you should document with XML documentation everything, that can be seen from the API point of view from your library. Finally, XML documentation can also be read by software development tools like Visual Studio, allowing it to provide help to the programmer, for example, as explanation of the functions during suggestions for code completion.

What should be documented with XML Comments?

What should you document, besides having the code written in a self-explanatory way:

• Public types.
• Public methods, properties of public types.

What should not be documented, because it needs to be self-explanatory by the code itself and API users will not see it:

• Any member of a private/internal type.
• Any private method or property.
• Any protected member of a public type that is sealed. The reason behind this, is that API users will not be able to derive the class, and thus will not be able to access the protected member anyway.

How to generate the XML documentation?

To generate the XML document output from your project, you need to enable it in the project properties: Project Properties / Build / XML documentation file. Check the checkbox and supply the output location. The automatically set output is usually proper and if you put the XML documentation file in the same directory as the assembly, it can be easily packed with the it. Doing so, will let your API users to have nice code display of your documentation.

How to generate different other formats of the documentation?

Another way to make use of the XML documentation comments in your code is to extract it to HTML and other formats and publish it on your website or other places related to your product. This can be useful when you are documenting, for example, a Web API. Though, it can also help API users when they have no access to sophisticated tool like Visual Studio, just using a text editor to write the code.

One such program to extract HTML documentation, beside other formats, is Doxygen.

How to install Doxygen on your build server?

The first step in getting doxygen to be installed on your build server is to install the executable from the doxygen Cygwin package. See my article, titled Building a Build Server – Building your first C# Project with Jenkins, for details on how to install Cygwin itself (section Installing Cygwin Git) and my article, titled Building a Builder Server – Installing NAnt, on how to add packages to your Cygwin installation. In the later article, during the first half, I added wget and unzip to the Cygwin installation. Installing the doxygen Cygwin package will result in having the executable of doxygen being placed in the Cygwin bin directory as doxygen.exe. The default binary directory of Cygwin installation – and the binary directory if you followed my installation steps and responses –, is C:\cygwin64\bin. This will result in having the Doxygen executable under C:\cygwin64\bin\doxygen.exe.

The next step is to install the doxygen plugin into Jenkins. The plugin is named Doxygen Plug-in in Jenkins, and can be installed under Manage Jenkins / Manage Plugins menu from the Jenkins main page. After the plugin installed, you need to configure the plugin under the menu Manage Jenkins / Global Tool Configuration. Add the following Doxygen installation in the Doxygen section:

Please note that giving the correct above path, for some reason, gives a warning from the Doxygen Plug-in, that it is not a directory. However, if you specify only the directory part, the warning goes away, but the commands executed during the build are going to be incorrect. This is most likely a small bug in the plugin itself.

Building a project with Doxygen documentation

To try out to build a project with documentation, feel free to use my example project, which only contains one XML documentation comment. This project is located at https://github.com/atzimler/XmlCommentLibrary. Besides having the XML Documentation added to the source code and configured to build as mentioned above, the following additions have been made to the project:

• With having the current directory as the main folder of the solution, doxygen -g was executed to generate a default doxygen configuration file, called Doxyfile.
• The default Doxyfile contains almost everything correctly for a C# project, but you need to switch on the recursive code file search. To do this, edit the Doxyfile and change the line “RECURSIVE = NO” to “RECURSIVE = YES”.
• To verify that you should in turn get an HTML documentation, rebuild the project with XML Documentation Comments and then execute doxygen from the same directory as the Doxyfile. You should get an html sub-directory, and the html/index.html page should contain your documentation comments. In the case of the above example library, it means that there should be a documentation entry for XmlCommentLibrary.PublicClass class.

The following Jenkins build instruction will pull my example GitHub project and build the documentation from it using doxygen. If you installed the doxygen plugin and executables correctly on the server it should result at the end of the build in a menu entry on the project page titled DoxyGen HTML. This also shows, how to set up the Doxygen build steps in the Jenkins project.

Create a project as a Freestyle project using the menu option New Item from the main Jenkins homepage.

Source Code Management

Build

Post-build Actions

That’s it, now your build server can generate API documentation for your class libraries. All you need to do is to create and maintain the content of the documentation correctly. Do not hesitate to share this article, if you know somebody who could benefit from having good quality library documentation automatically generated. Stay with me next week, when we are going to play with automatic execution of unit tests on the build server. Please follow me on Twitter or LinkedIn.

By subscribing to the email list, you will be notified about new posts.

Name

Email*