Sandcastle not documenting Property summaries

Question

I'm using SandCastle with the HelpBuilder GUI for the first time today to help create an API of some of our exposed functions and properties. I've included /// <summary> ... </summary on a number of the properties where I felt they would benefit from an extra documentation or examples of use.

When I build the output file to chm, I'm not seeing the summary descriptions at all. All of property members are listed, but their descriptions are blank. I've rebuilt the project, and tried a few different settings in SandCastle, but they're still not showing up.

Is there something obvious I'm overlooking? Does SandCastle not read property summaries? Or do summaries need a different keyword?

Answer 1

You have to tell Visual Studio to generate the XML documentation file at compile time: just set the corresponding project property as described here: http://msdn.microsoft.com/en-us/library/vstudio/x4sa0ak0(v=vs.100).aspx

After that, Sandcastle will output the "summary" comments in the "Description" column.

Answer 2

From the Sandcastle Common Issues Help page:

Missing Code Comments in Documentation

By default, all of a project's XML documentation is expected to be in a single file named, comments.xml. If you have multiple XML documentation files then place them in a new folder named, Comments and adjust sandcastle.config to use a wild card instead, as in the following example.

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
           assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
  <index name="comments" value="/doc/members/member"
         key="@name" cache="100">
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727"
          recurse="false" files="*.xml" />

    <data files="Comments\*.xml" />  <!-- This line was modified -->

  </index>
  <copy name="comments" source="*" target="/document/comments" />
<components>

For more information, see this blog post.