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

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.

Answer 2

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 3

It looks like another answer was already accepted as working, but I'm going to add my solution since I had the same issue but for another reason.

If you open up the XML file that you are using as your Documentation Source, control-f the method/property that you wrote comments for but isn't showing up in your final sandcastle doc. If you see the message:

Badly formed XML comment ignored for member "M: ...

Then, like me, you probably included some characters that XML wasn't too happy about. I used the "&" in a comment, but XML will yell at you if you use "<" or ">" as well. Fix your comment and you should be good to go!