Source XML comments not in generated documentation

Topics: Bugs, General Questions
Mar 27, 2008 at 12:31 PM
Edited Mar 27, 2008 at 12:54 PM
I've just installed 1.10.1 RC. I'm testing it out on a small project, but I can't get any of the XML comments in my source code to appear in the generated documentation. This is a similar problem to one raised previously ( I'm also using VS2005 SP1 and the January 2008 release of Sandcastle.

I've set "Merge xml documentation" in Options to "KeepSource", is there anything else that needs to be set up before my XML comments make it into the documentation? I've tried changing this setting back to its default value (Overwrite), but this makes no difference. However, in contrast to the topic referenced above, the XML file under buildhelp\assembler\comments does not contain any of my XML comments. It also doesn't have any info for any Properties in my classes (not sure if they're supposed to be there, though).

Am I missing some extra settings?
Mar 27, 2008 at 3:17 PM

The Merge xml documentation setting only has an effect when external XML documentation that you created using DocProject's Topic Editor conflicts with the comments from your source code. This setting is not typically needed though since it's unlikely that a conflict will occur, unless you purposefully want to overwrite code comments with external comments.

Try the following instead:
  1. Enable XML documentation output in your source project if you haven't already. (See How to: Generate XML Documentation for a Project .)
  2. Make sure that DocProject knows about your XML documentation file:
    1. If your source project was added as a project reference then you don't have to do anything. DocProject will automatically use the XML documentation file from the source project.
    2. If you're using an external source then you must add it to the XML Documentation column in the External sources dialog.
  3. Build the source project and make sure that the XML documentation file is in your project's bin folder and that it has content.
  4. Build your DocProject or DocSite and check the buildhelp\assembler\comments folder again to see if it was imported.
If you still have a problem let me know.

- Dave
Mar 28, 2008 at 9:50 AM
Oops! Thanks, it works fine now. I'd forgotten to tell Visual Studio to generate the XML file.
Thanks a lot for this great tool.