Clarification and Correction for Adding Commented Regions in VB.NET Code

Topics: User Forum
Jun 28, 2013 at 5:41 PM
In Sandcastle's documentation on the <code> Block Element, the information about extracting commented regions from the interior of Class Methods and Functions needs some clarification and possibly a minor correction.

This capability is a fantastic extension of Visual Studio's XML auto-documentation feature. Usually, you can only add XML annotations to elements declared at the Class level; you can't add XML annotation inside methods and functions. Sandcastle's "Code Block Component", however, will recognize artificial '#Region's of comments and code that are INSIDE your methods, and extract them to the Help File.
(At the bottom of this article, please see a possible correction for naming the commented #Region.)

All you need to do in the XML note is provide a <code> tag that includes the region's name and the location of the source file. And therein lies the rub: the XML note for a method is located inside the Class file you are documenting. Wouldn't the obvious path to the Class file simply be just the name of the file?

Sandcastles documentation on "source, region, and removeRegionMarkers" says,
The source attribute is used to specify that the code block's content should be read from an external source code file.
Here's the trick: Sandcastle considers ALL the files in the project you are documenting as external, external that is to the Sandcastle sub-project of your main project. So the path to the 'external' source file must be constructed relative to the Sandcastle project, NOT to the Class file!

Here is a likely scenario. The Classes you are documenting are in the top level of your main project. The Sandcastle sub-project probably is located within (below) the main project.
      Main Project
            Sandcastle Project
                  Sandcastle Project Properties
                  Sandcastle Documentation Sources
                  Sandcastle References
Inside Class1.vb, you have a method with XML documentation. Inside the method, you have identified a commented #region you want to add to your Help File. To do this, add a <code> element to the <remarks> of the XML note. In the 'source' attribute, identify the location of the Class file in relation to the Sandcastle Project. In the above case, that would be in the parent folder to Sandcastle. Like this:
<code source="..\Class1.vb" region="Selection Object" />
    ''' <summary>
    ''' Notes for 'ButtonProceed_Click' in Class1.vb
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="e"></param>
    ''' <remarks>
    ''' To have Sandcastle include comments and code from within this method, provide the path to the Class1.vb file in relation to the Sandcastle project. 
    ''' Likely location: parent folder of the Sandcastle project.
    ''' <code source="..\Class1.vb" region="Selection Object" />
    Private Sub ButtonProceed_Click(sender As System.Object, e As System.EventArgs) Handles ButtonProceed.Click
        ' #Region "Selection Object"
        ' Create a Selection Object for the current document 
        ' and then move the cursor to the top of the document.
        Dim myApp As Microsoft.Office.Interop.Word.Application = Globals.ThisAddIn.Application
        Dim sel As Word.Selection = myApp.Selection
        With sel
            .ExtendMode = False
            .HomeKey(Unit:=WdUnits.wdStory, Extend:=WdMovementType.wdMove)
        End With
        ' #End Region
    End Sub
Lastly, here's a possible correction: In VB.NET, the names of Class level '#Region's must be put inside quotation marks. Sandcastle's documentation on internal regions doesn't use quotation marks for the name.
' #Region VB.NET Snippet
I don't know if putting the internal, commented region name in quotes will make any difference to Sandcastle's Code Block Component. However, I do know that it won't break Sandcastle if you do. Like this:
' #Region "VB.NET Snippet"
Hope this helps.
Noel C. Gordon.
Jun 29, 2013 at 10:35 PM
For regions in comments in VB.NET method bodies or other non-code files, the code block component will find them with or without the enclosing quote marks on the region name. I've updated the code block component and code element documentation so that the VB.NET example uses quotes around the commented region name so that it's consistent with standard VB.NET conventions for class level regions. I also added a note that better describes the relative nature of the path to the documentation project.