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.
Sandcastle Project Properties
Sandcastle Documentation Sources
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" />
''' Notes for 'ButtonProceed_Click' in Class1.vb
''' <param name="sender"></param>
''' <param name="e"></param>
''' 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
.ExtendMode = False
' #End Region
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.