Click here to Skip to main content
65,938 articles
CodeProject is changing. Read more.
Articles / Languages / VB

CodeGen - Making XML Comments

0.00/5 (No votes)
10 Aug 2015CPOL 6.7K  
Utility class for adding XML comment to auto-generated code

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:

VB
 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:

VB
Imports Microsoft.CodeDom.Providers.DotNetCompilerPlatform

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

VB
''' <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.

VB
''' <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:

VB
''' <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

  • 10th August, 2015: Initial version

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)