SubMain - CodeIt.Right The First Time!

/Community

Support Community for SubMain Products
 Home Products Services Download Purchase Support
in Search
 
Home Forums Blogs Tutorials/CIR Tutorials/GD Downloads
Welcome to SubMain Community Sign in | Join | Help

Tutorials

XML Comment template: IntelliComment or XML Comment Stub?

One of the very helpful and important rules that we added in the past few months is the one that finds members that missing XML documents when these are required - General / Type, Member -> Should have XML comments (Externally visible types and members should have XML comments).

One of the most frequently asked question about the rule is why some users are not seeing the missing XML comment violation on select project. There are two possible reasons for that:

  1. The rule will only trigger violation on public and protected members in its default configuration. If you choose to have it validate private and/or static members, you will need to edit the rule's Scope property to include those as well.
  2. The option to generate XML documentation is turned OFF in  your project. In this case the rule doesn't the missing XML comment violation to reduce false positives since the project setting state it does not need XML documentation.

To turn the option to generate documentation ON, in C# project, go to project Properties -> Build -> XML documentation file

XMLComment1

In VB project, go to project Properties -> Compile -> Generate XML documentation file

XMLComment2

In the spirit of CodeIt.Right the rule offers two automatic correction options - IntelliComment and XML Comment Stub. In the default configuration these are fairly similar, the difference is that IntelliComment will fill in the generated XML Comment using data from our GhostDoc engine, while the Stub template will create an empty XML Comment Stub.

Here is example generated by IntelliComment template

    /// <summary>
    /// Determines the size of the page buffer.
    /// </summary>
    /// <param name="initialPageBufferSize">Initial size of the page buffer.</param>
    /// <returns></returns>
    /// <remarks></remarks>
    public int DeterminePageBufferSize(
                           int initialPageBufferSize) {

        // Implement the method here
        return 1;

    }

And example generated by XML Comment Stub template

    /// <summary>
    ///  
    /// </summary>
    /// <param name="initialPageBufferSize"> </param>
    /// <returns></returns>
    /// <remarks></remarks>
    public int DeterminePageBufferSize(
                           int initialPageBufferSize) {

        // Implement the method here
        return 1;

    }

So, the rule offers two correction option - it is up to you to pick which template works best for your project.

I notice that I keep using the word "template" when describing the two correction options. That is because these are true T4 templates that you can customize to fit your team requirements.

Here is default IntelliComment template:

<#@ template language="C#" #>
<#
    CodeElement codeElement = Context.CurrentCodeElement;
#>
/// <summary>
/// <#= codeElement.XmlComment.SummaryTagText #>    
/// </summary>
<#
    if(codeElement.HasTypeParameters) 
    {
        foreach(TypeParameter typeParameter in codeElement.TypeParameters) {
#>
/// <typeparam name="<#= typeParameter.Name #>"><#= typeParameter.XmlComment.TypeParamTagText #></typeparam>
<#
        }
    }
    
    if(codeElement.HasParameters) 
    {
        foreach(Parameter parameter in codeElement.Parameters) {
#>
/// <param name="<#= parameter.Name #>"><#= parameter.XmlComment.ParaTagText #></param>
<#
        }
    }
    
    if(codeElement.HasReturnType) {
#>
/// <returns><#= codeElement.XmlComment.ReturnsTagText #></returns>
<#
    }
    
    if(codeElement.IsProperty) {
#>
/// <value><#= codeElement.XmlComment.ValueTagText #></value>
<#
    }    
    
    if(codeElement.IsMember) {
#>
/// <remarks></remarks>
<#
    }    
#>

As you can see it is very much self-explanatory and you can customize it to your needs. For example, in combination with the CodeIt.Right Global Properties feature, we can have <reviewed/> and <copyright/> data automatically when we add the following at the very end of the template:

/// <reviewed><#= Context.GetGlobalProperty("UserName") #></reviewed>
/// <copyright><#= Context.GetGlobalProperty("CompanyName") #> Copyright <#= System.DateTime.Now.Year.ToString() #></copyright>

Pretty powerful stuff, huh?

Published Thursday, January 28, 2010 4:39 PM by Serge B. (SubMain)

Comments

No Comments
Anonymous comments are disabled
    
 
     
 
Home |  Products |  Services |  Download |  Purchase |  Support |  Community |  About Us |