Source Documentation

Documentation... The most hated word in software development.  Programmers can't stand doing documentation and will avoid it at all cost.

So, it's best to make it easy for them to do, and conduct code reviews to ensure it's being completed.  I'm not talking about source code comments regarding the logic, I'm talking base classes, interfaces, and components that are used everywhere and demand a specific usage.

One of the biggest reasons why developers don't do this is because source code and documentation are often in two different location and they always get out-of-sync so why invest the effort.  This is a very valid reason, however as I mentioned in my post about retaining senior staff this can cause major issues down the road.

It's best to keep your source code and documentation in the exact same spot, this will allow developers to quickly and easily update the documentation based on changes in the source code. This also allows the documentation to be versioned along with the source changes.  When other developers have to use or update your code, there is clear documentation of your intentions.

Visual Studio was updated to produce xml formatted docmentation based on special comment tags beginning with \\\ will be processed.  You can also use special <XML> tag and have your output formatted differently.

In your source code, MyClass.cs, you can add the \\\ comment above the class, interface, method, etc... that you want to document.

    /** <summary>

     * ITranslator provides methods for callers to get a translation.  Implementers of ITranslator have to
     * preform the translation requested.
     * </summary>
     * <example>
     *      When receiving a ITranslationItems object when implementing Translate the sender can be
     *      enumerated as shown below.
     *      <code>
     *          foreach(var item in sender.TranslationItems()) {
     *   
     *              // Get translatable strings from the class
     *              //implementing ITranslationItems
     *         
     *              String lbls = item.Label;
     *
     *              if (lbls == null) continue; //No Label set
     *
     *              // 3. perform translations   
     *              lbls = map.GetTranslation(destinationlang, lbls);
     *
     *              //Set Translated Label to be used
     *              item.Label = lbls;
     *          }
     *        </code>
     *     </example>
     */
    public interface ITranslator {


Update your project file to output xml documentation and source code lines beginning with \\\ above will be generated with your assembly myCode.dll and myCode.xml.

Below is a sample of the output generated from Visual Studio.

<?xml version="1.0"?>

<doc>
    <assembly>
        <name>myCode</name>
    </assembly>
    <members>
        <member name="T:Translation.NamespaceDoc">
            <summary>
            The Translation namespace is used to by application link objects with items requiring translation to avialable translation providers.  Providers must implement the iTranslator interface.
            </summary>
        </member>
        <member name="T:Translation.ITranslatable">
            <summary>
             ITranslator provides methods for callers to get a translation.  Implementers of ITranslator have to  preform the translation requested.
             </summary>
             <example>
                  When receiving a ITranslationItems object when implementing Translate the sender can be enumerated as shown below.
                  <code>
                      foreach(var item in sender.TranslationItems()) {
                          // Get translatable strings from the class
                          // implementing  ITranslationItems

                          String lbls = item.Label;

                          if (lbls == null) continue; //No Label set

                          // 3. perform translations
                          lbls = map.GetTranslation(destinationlang, lbls);

                          //Set Translated Label to be used

                           item.Label = lbls;

                      }

                    </code>
                 </example>
        </member>
...


An XML formatted document is hardly usable documentation, and if you only have Visual Studio then that's all you get.  You have to download some additional applications to package your work into a pretty and professional outputs.  Luckly it's not going to cost the company a dime, first download Sandcastle, it will compile your xml and process your assembiles to generate a great documentation in a number of formats.  Then download Sandcastle Builder because sandcastle doesn't have a GUI and it's much easier to setup a project using Sandcastle Builder.

Create a new project using Sandcastle Builder and add documentation sources, your assemblies and your generated xml files.  There are four supported HelpFileFormats available, HtmlHelp (.chm), MSHelp, MSHelpViewer (Visual Studio integrated help), and Website.

After you compile your project you will end up with a great looking help file.

Now you can distribute your source documentation to your team, or even better yet!!! Include the documentation building in your build process. Add the following lines (with your paths and filenames) to your CruiseControl.NET installation (ccnet.config) and generate versioned documentation with your versioned application.

<!-- BUILD DOCUMENTATION -->
<exec>
   <executable>C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe</executable>
   <baseDirectory>C:\Dev\DeveloperDocs\Sandcastle\Projects</baseDirectory>
   <buildArgs>/p:Configuration=Debug CoreFramework.shfbproj</buildArgs>
   <buildTimeoutSeconds>0</buildTimeoutSeconds>
</exec>

<!-- Package DOCUMENTATION -->

<exec>
   <executable>C:\Program Files (x86)\Inno Setup 5\ISCC.exe</executable>
   <baseDirectory>C:\Dev\DeveloperDocs\Sandcastle\Projects</baseDirectory>
   <buildArgs>CoreFramework.iss</buildArgs>
</exec>

Note: CoreFramework.iss is an InnoSetup file, generate your own using the built-in script wizard.


I hope this article was helpful, let me know if you have any questions.