Documentation is an essential part of any IT project, especially when you are creating reusable components that will be used by other developers (such as class libraries). Without
documentation re-using a class library is almost impossible. Just think of coding .net applications without MSDN
documentation (Ooops I can’t think of it). Normally developers, who know
the bits and pieces of their classes, see this as a boring work to write details again to generate
the documentation. Also
the amount of work to make this and manage it changes made
the process of manual creation of
Documentation impossible or tedious. So what is
the effective solution? Let me divide this into two steps 1. Generate comments for your code while you are writing
the code. 2. Create
documentation file using these comments. Now I am going to examine these processes. Step 1: Generate XML Comments automatically Most of
the developers write comments for their code.
The best thing is that
the comments will be entered during
the development process. Additionally comments give a good reference to
the code, make your code more manageable/readable. Later these comments can be converted into
documentation, along with your source code by identifying properties and methods I found an add-in for visual studio, GhostDoc that automatically generates XML
documentation comments for C#.
The add-in is available in Visual Studio Gallery at MSDN. You can download this from
the url http://visualstudiogallery.msdn.microsoft.com/en-us/46A20578-F0D5-4B1E-B55D-F001A6345748. I downloaded
the free version from
the above url.
The free version suits my requirement. There is a professional version (you need to pay some $ for this) available that gives you some more features. I found
the free version itself suits my requirements.
The installation process is straight forward. A couple of clicks will do
the work for you.
The best thing with GhostDoc is that it supports multiple versions of visual studio such as 2005, 2008 and 2010. After Installing GhostDoc, when you start Visual studio,
the GhostDoc configuration dialog will appear.
The first screen asks you to assign a hot key, pressing this hotkey will enter
the comment to your code file with
the necessary structure required by GhostDoc. Click Assign to go to
the next step where you configure
the rules for generating
the documentation from
the code file. Click Create to start creating
the rules. Click finish button to close this wizard. Now you performed
the necessary configuration required by GhostDoc. Now In Visual Studio tools menu you can find
the GhostDoc that gives you some options. Now let us examine how GhostDoc generate comments for a method. I have write
the below code in my code behind file. public Char GetChar(string str, int pos) { return str[pos]; } Now I need to generate
the comments for this function. Select
the function and enter
the hot key assigned during
the configuration. GhostDoc will generate
the comments as follows. /// <summary> /// Gets
the char. /// </summary> /// <param name="str">The STR.</param> /// <param name="pos">The pos.</param> /// <returns></returns> public Char GetChar(string str, int pos) { return str[pos]; } So this is a very handy tool that helps developers writing comments easily. You can generate
the xml
documentation file separately while compiling
the project. This will be done by
the C# compiler. You can enable
the xml
documentation creation option (checkbox) under Project properties -> Build tab. Now when you compile,
the xml file will created under
the bin folder. Step 2: Generate
the documentation from
the XML file Now you have generated
the xml file
documentation. Sandcastle is
the tool from Microsoft that generates MSDN style
documentation from
the compiler produced XML file.
The project is available in codeplex http://sandcastle.codeplex.com/. Download and install Sandcastle to your computer. Sandcastle is a command line tool that doesn’t have a rich GUI. If you want to automate
the documentation generation, definitely you will be using
the command line tools. Since I want to generate
the documentation from
the xml file generated in
the previous step, I was expecting a GUI where I can see
the options. There is a GUI available for Sandcastle called Sandcastle Help File Builder. See
the link to
the project in codeplex. http://www.codeplex.com/wikipage?ProjectName=SHFB. You need to install Sandcastle and then
the Sandcastle Help file builder. From here I assume that you have installed both sandcastle and Sandcastle help file builder successfully. Once you installed
the help file builder, it will be available in your all programs list. Click on
the Sandcastle Help File Builder GUI, will launch application. First you need to create a project. Click on File -> New project
The New project dialog will appear. Choose a folder to store your project file and give a name for your
documentation project. Click
the save button. Now you will see your project properties. Now from
the Project explorer, right click on
the Documentation Sources, Click on
the Add
Documentation Source link. A
documentation source is a file such as an assembly or a Visual Studio solution or project from which information will be extracted to produce API
documentation. From
the Add
Documentation source dialog, I have selected
the XML file generated by my project. Once you add
the xml file to
the project, you will see
the dll file automatically added by
the help file builder. Now click on
the build button. Now
the application will generate
the help file.
The Build window gives to
the result of each steps. Once
the process completed successfully, you will have
the following output in
the build window. Now navigate to your Help Project (I have selected
the folder My Documents\Documentation), inside help folder, you can find
the chm file. Open
the chm file will give you MSDN like
documentation.
Documentation is an important part of development life cycle. Sandcastle with GhostDoc make this process easier so that developers can implement
the documentation in
the projects with simple to use steps.
