Designer.vb Summary and Remarks Ignored

Topics: Developer Forum, User Forum
Mar 20, 2014 at 2:16 PM
I am using Sandcastle Version 2014.2.15.0 Beta to generate documentation for my ASP.NET 3.5 WAP. Although the summary and remarks are showing in the designer.vb as well as the project generated XML, they are not being added to the Sandcastle output.

I have also tried declaring the controls in the code-behind page to no avail.

Do you have any suggestions? Is this supported in Sandcastle? If not, would you know of any products that this is supported in?

I love using Sandcastle so here's hoping the problem is between the keyboard and the chair.
Mar 20, 2014 at 3:03 PM
Check the build log. It will tell you which XML comments file it's using. Perhaps the configuration is not correct (Debug vs Release). Also, do you mean that the comments aren't appearing on the members or that the members just aren't appearing in the help file? If the latter, it is probably because they are private. By default, only public members are included. The Visibility category of project properties can be used to control which items are included if that's the case.

Mar 20, 2014 at 5:33 PM
Edited Mar 20, 2014 at 5:38 PM
Thank you for the reply!

The comments aren't showing up in the help file. The members, in this case Fields, are.

In the designer.vb I have:
    '''lblTitle control.
    '''Auto-generated field.
    '''To modify move field declaration from designer file to code-behind file.
    Protected WithEvents lblTitle As Global.System.Web.UI.WebControls.Label
The following is showing up in the Build.XML. I have all items checked for Visibility. In the API filter I have all Protected Properties and Protected Fields checked.
<member name="F:PROJECTNAME.DefaultPage.lblHome">
    <summary>lblHome control.</summary>
    <remarks>Auto-generated field.To modify move field declaration from designer file to code-behind file.</remarks>
I should note that I have but the code in the code behind file and it not show there as well.
  • Steve
Mar 20, 2014 at 6:45 PM
Based on your example, I have a feeling this is a known issue caused by how the VB compiler works. See this thread:
and the one it references:

Is that perhaps what you are seeing?

Marked as answer by SJMcGrath on 3/20/2014 at 12:39 PM
Mar 20, 2014 at 6:59 PM
Edited Mar 20, 2014 at 7:23 PM
It very well could be. I have neither of the below in my build file:
That being said, when I open the documentation file I see:
I guess that is the compiler issue that you are talking about. I guess Sandcastle is using the compiler and that is when the underscore gets injected.

Do you know of any other products that may be helpful in generating ASP.NET Control documentation? I've googled myself blind :)
Mar 20, 2014 at 7:30 PM
If I add the following and edit the API filter not to show the fields or properties, I get the desired result. Of course there are no detail pages for those items but that is ok. I'm just looking to have a landing page that will explain which fields do what and why on the web form.

I only recommend this approach for the extremely desperate!
''' <summary>
''' Home page of the Web.
''' <p/>
''' <table id="myList" class="members">
''' <tr>
''' <th class="ps_iconColumn"></th>
''' <th class="ps_nameColumn">Name</th>
''' <th class="ps_descriptionColumn">Description</th>
''' </tr>
''' <tr data="protected;declared;notNetfw;">
''' <td><img src="./../icons/protproperty.gif" alt="Protected Property" title="Protected property" /></td>
''' <td><b>lblTitle</b></td>
''' <td><div class="summary">Title of the Page</div></td>
''' </tr>
''' <tr data="protected;declared;notNetfw;">
''' <td><img src="./../icons/protproperty.gif" alt="Protected Property" title="Protected property" /></td>
''' <td><b>lblHome</b></td>
''' <td><div class="summary">Label for storing retreived text </div></td>
''' </tr>
''' </table>
''' </summary>
''' <remarks>The links on the left hand side of the page will allow you to navigate.</remarks>
Mar 20, 2014 at 11:15 PM
As noted in the MSDN topic, you could maintain a standalone XML comments file which would be like managing one for project and namespace comments. You'd basically clone the field XML comments and change the prefix to "P:" in the member IDs.