Sandcastle Help File Builder not showing documentation for xml comments for html/asp.net elements in .ascx.designer.vb file

Question

I am using Sandcastle Help File Builder to build the documentation for a VB.net project but the documentation for the asp.net/html elements are not appearing.

The xml comments for these are defined in the .ascx.designer.vb file for the respective Web Form or Web Forms User Control. An example of this code is as follows:

Partial Public Class WebUserControl    
    '''<summary>
    '''TblsDiv control.
    '''</summary>
    '''<remarks>
    '''Auto-generated field.
    '''To modify move field declaration from designer file to code-behind file.
    '''</remarks>
    Protected WithEvents TblsDiv As Global.System.Web.UI.HtmlControls.HtmlGenericControl 
End Class

In the help file created by Sandcastle Help File Builder, the documentation for these elements appear blank as if there were no xml comments.

Is this an issue with Sandcastle Help File Builder or is there another way to add xml comments to the respective html/asp.net elements?

Answer 1

After doing some research the only thing I have found was a very old answer Protected Withevents not documenting properly of the developer of SHFB from the year 2007.

The VB.NET compiler performs some stuff behind the scenes that causes this problem. In the XML comments file, the "bw" member is documented as a field (F:AbstractApp.bw) which on the surface appears to be correct. However, the compiler converts it to a private field (_bw), decorates it with an AccessedThroughProperty attribute, and creates a protected property called "bw" (P:AbstractApp.bw). As such, the XML comments get ignored because they now refer to a field that doesn't exist and there are no comments for the compiler generated property. What's also interesting is that the property won't show up until you include internal or private members in the documentation build because _bw is private so it doesn't see the property if they are omitted.

It's a pain to have to do it, but what you could do is create a "Comments Only" XML file and add the XML comments to it for the properties that the compiler creates. The other option, if they aren't that relevant is to turn off the document privates and internals options or use the API filter to get rid of them so that they don't show up in the documentation at all.

But it seems to me this is a problem remaining today.

Please note I'm not a ASP.net developer and I can test this using Visual Studio Community 2015 and Sandcastle Help File Builder (SHFB) Version 2019.15.9.0 at this stage only.

My code snippet for testing in a WebUserControl1.ascx.vb:

''' <summary>
''' TEST Sandcastle Help File Builder (SHFB)
''' </summary>
Partial Public Class WebUserControl
  '''<summary>
  '''TblsDiv control.
  '''</summary>
  '''<remarks>
  '''This is for test case only.
  '''Sandcastle Help File Builder (SHFB) not showing documentation for xml comments for html.
  '''</remarks>
  Protected WithEvents TblsDiv As Global.System.Web.UI.HtmlControls.HtmlGenericControl


End Class

Building the solution is resulting in a file WebForms_Basic.xml I added as a documentation source in SHFB's project explorer.

<member name="T:WebApplication2.WebUserControl">
 <summary>
 TEST Sandcastle Help File Builder (SHFB)
 </summary>
</member>
<member name="F:WebApplication2.WebUserControl._TblsDiv">
<summary>
TblsDiv control.
</summary>
<remarks>
This is for test case only.
Sandcastle Help File Builder (SHFB) not showing documentation for xml comments for html.
</remarks>
</member>

Building help file - you know - is resulting in:

Editing the following line in WebForms_Basic.xmland building the help files without building the solution

<member name="P:WebApplication2.WebUserControl.TblsDiv">

is resulting in what you expected. You need to adapt this for your needs.