CodeGen - Making XML Comments

Introduction

The CodeDOM allows for automatic generation and compilation of code - however, even when code is automatically generated, it is good practice to add comments. This tip / class makes for rapid addition of the XML comment sections.

Background

For background on code generation with CodeDOM, refer to the MSDN documentation.

Using the Code

To generate (for example) a VB "remarks" comment that has two lines:

 Dim commentLines As New List(Of String)
 commentLines.Add("Line 1")
 commentLines.Add("Line 2")
Dim remarksComment = CommentGeneration.RemarksCommentSection(commentLines)

Source Code

Everything needs a reference to the Roslyn compilers:

    Imports Microsoft.CodeDom.Providers.DotNetCompilerPlatform

Then we need two functions that create the start and end tag for the XML comment:

    ''' <summary>
    ''' Create a comment to start an XML comment section
    ''' </summary>
    ''' <param name="sectionName">
    ''' The name of the section - remarks, summary, returns, param etc.
    ''' </param>
    ''' <param name="sectionAttributes">
    ''' Additional attributes to put in the open section tag (optional)
    ''' </param>
    Public Shared Function OpenCommentSection(ByVal sectionName As String, 
           ByVal sectionAttributes As Dictionary(Of String, String)) As CodeCommentStatement

        Dim commentInner As String = sectionName

        If (sectionAttributes IsNot Nothing) Then
            For Each sectionNameAttribute As String In sectionAttributes.Keys
                commentInner &= " " & sectionNameAttribute & _
                       "=""" & sectionAttributes(sectionNameAttribute) & """"
            Next
        End If

        Return New CodeCommentStatement("<" & commentInner.Trim & ">", True)

    End Function

    Public Shared Function CloseCommentSection(ByVal sectionName As String) _
                                               As CodeCommentStatement

        Return New CodeCommentStatement("</" & sectionName.Trim & ">", True)

    End Function

Then we build on these to make a generic method that can put any number of comments in a named section.

    ''' <summary>
    ''' A general function to wrap a comment in XML documentation attributes
    ''' </summary>
    ''' <param name="sectionName">The name of the section - e.g. summary, 
    ''' remarks, returns </param>
    ''' <param name="commentText">The content of the section
    ''' </param>
    ''' <returns>
    ''' A code comment collection that can be attached to anything that takes XML comments
    ''' </returns>
    Public Shared Function BaseCommentSection(ByVal sectionName As String,
                      ByVal sectionAttributes As Dictionary(Of String, String),
                      ByVal commentText As IEnumerable(Of String)) 
                                            As CodeCommentStatementCollection

        Dim ret As New CodeCommentStatementCollection()

        ret.Add(OpenCommentSection(sectionName, sectionAttributes))
        For Each commentLine As String In commentText
            ret.Add(New CodeCommentStatement(commentLine, True))
        Next
        ret.Add(CloseCommentSection(sectionName))

        Return ret

        End Function

Then we wrap each comment section up in a function, depending on whether it does or does not expect named properties:

    ''' <summary>
    ''' Add a remarks comment section
    ''' </summary>
    ''' <param name="commentText">
    ''' The lines of comment to put in the remarks section
    ''' </param>
    Public Shared Function RemarksCommentSection(ByVal commentText As IEnumerable(Of String)) _
                                                 As CodeCommentStatementCollection

        Return BaseCommentSection("remarks", Nothing, commentText)

    End Function

History

• 10^th August, 2015: Initial version