Generating Documentation with JustCode

If you enjoy writing documentation from scratch, this article may not be for you. If you like removing as much repetitive work as possible, then JustCode can help you out. Aside from aiding in this endeavor with code, it also addresses code documentation.

There are two primary features in JustCode I will discuss. The first is Generate Documentation which handles the XML comments for methods and types. The second is a new feature, Introduce Header, which was made available on May 3rd with internal build 1.

Generate Documentation

I like self-documenting code. I write short, descriptive methods intended for anyone to be able to follow. Unit tests are another form of documentation for the coder, since they describe and prove the functionality for a particular unit of code. Code documentation is used for other purpose. It allows one to specify nuances pertaining to a particular unit of code, or leave remarks such as why a particular algorithm was chosen. Project management will also require code documentation that can be used to generate deliverables for other teams.

Here is a method from the StoryService in the Kigg open source project:

public virtual void Promote(IStory theStory, IUser byUser, string fromIPAddress)
{
    Check.Argument.IsNotNull(theStory, "theStory");
    Check.Argument.IsNotNull(byUser, "byUser");
    Check.Argument.IsNotEmpty(fromIPAddress, "fromIPAddress");

    using(IUnitOfWork unitOfWork = UnitOfWork.Begin())
    {
        if (theStory.Promote(SystemTime.Now(), byUser, fromIPAddress))
        {
            _eventAggregator.GetEvent<StoryPromoteEvent>()
                            .Publish(new StoryPromoteEventArgs(theStory, byUser));

            unitOfWork.Commit();
        }
    }
}

Code documentation is typically added through xml comments. Visual Studio will get you started if you type /// above the method signature. It will add a section for a summary of the method, descriptions for the parameters and return values.

/// <summary>
/// 
/// </summary>
/// <param name="theStory"></param>
/// <param name="byUser"></param>
/// <param name="fromIPAddress"></param>
public virtual void Promote(IStory theStory, IUser byUser, string fromIPAddress)

This is better than nothing, but much of the information required for the documentation can be inferred based on the names; that is the point of writing self-documenting code. That’s where JustCode comes in. There is no need to generate the initial XML comments. Instead, put your cursor on the method name and press Ctrl+Shift+D.

/// <summary>
/// Promotes the specified the story.
/// </summary>
/// <param name="theStory">The story.</param>
/// <param name="byUser">The by user.</param>
/// <param name="fromIPAddress">From IP address.</param>
public virtual void Promote(IStory theStory, IUser byUser, string fromIPAddress)

The StoryService class implements IStoryService, which defines the Promote method. If documentation exists in the interface, JustCode will use it instead. I created XML comments on the IStoryService.Promote method and cleaned it up to account for the articles and prepositions used for the parameter names. I also included a remark. I then repeated the procedure above.

/// <summary>
/// Promotes the specified story.
/// </summary>
/// <param name="theStory">The story to be promoted.</param>
/// <param name="byUser">The user promoting the story.</param>
/// <param name="fromIPAddress">The ip address of the user.</param>
/// <remarks>I wrote this on the IStoryService interface.</remarks>
public virtual void Promote(IStory theStory, IUser byUser, string fromIPAddress)

I mentioned before that this is typically used to generate documentation deliverables. If you’re interested in this, check out Sandcastle. 

Introduce Header

Whether it is for copyright purposes or inline history tracking required to pass certification, some projects require headers in source code files. There are a few options for this, such as creating your own file templates. With the May 3rd, 2011 release of JustCode it is a key chord: Ctrl+R, Ctrl+H.

Unlike xml comments, headers are typically shared with a team for a particular solution. To create headers in JustCode, you will need to enable options sharing. Click the JustCode menu, then Options.

In the dialog, select Options Sharing. If you have not done so, click the Create solution options button. Otherwise, click the Edit solution options button. The <solution>.jcsettings.xml file should be checked into version control since it’s purpose is to share settings for code cleanup.

I copied the license from the website and added it in File Header Text under Common.

With the cursor on the namespace line in a source file, the Introduce Header option is available. The shortcut key chord is Ctrl+R, Ctrl+H.

This works in JavaScript files as well as long as you are not within a code block.

Quick Reference

The menu options are available under JustCode | Code.

Generate Documentation: Ctrl+Shift+D
Context: select the symbol

Introduce Header: Ctrl+R, Ctrl+H
Context: namespace line (C#, VB) or outside of code block (JavaScript)

Conclusion

JustCode makes it easier for you to generate code documentation and headers. Introduce Header is a new feature, and I am interested to hear your feedback. Many people don’t use headers, but if you do so, does it fit your needs? Is there more you would like to see in future iterations of JustCode?