Single Source Code Not Picked Up By Sandcastle

Topics: Developer Forum, User Forum
Nov 16, 2011 at 2:34 AM

I have just started working on an existing API documentation project at a new company, and I have noticed that there is a lot of content in our API CHM files that appears to be missing. Our project uses single-source coding for desktop and mobile applications, and as far as I can see, only the desktop arguments are being picked up by Sandscastle. For example:

#if WindowsCE
// Summaries, comments etc. always ignored in Sandcastle, but not classes, methods etc. Greyed out in Visual Studio.
#else Desktop
// Everything always detected normally in Sandcastle
#endif

and

#if WindowsCE
// Summaries, comments etc. always ignored in Sandcastle , but not classes, methods etc. Greyed out in Visual Studio.
#endif

The sections of code that contain material being ignored are all greyed out in Visual Studio 2010. Is this a problem with preprocessors, or conditional compilation? As far I can tell, this problem is a longstanding one that has been around for years at this installation, but I would like to fix it. This is also my first experience usign Sandcastle, so I'm a little in the dark when it comes to possible solutions. Any tips or suggestions would be greatly appreciated!

Nov 16, 2011 at 2:44 AM

Just a note, XML comments are started with /// not //.

>> Is this a problem with preprocessors, or conditional compilation?

The grayed portion is an indication it is not being compiled or included in the compilation process.

This is most likely not Sandcastle problem but your configuration. If you are using conditional compilation,
you will have to compile for each condition and repeat the process for each condition for the Sandcastle too.

Also, check your XML comment output file to see which comments are included.

Best regards,
Paul. 

Nov 16, 2011 at 9:42 PM

So is there no way to get Sandcastle to produce results for all/both conditions at the same time? I'm guessing the easiest way to get results, if this is the case, might be to create individual outputs then merge them together using an external tool, then compile both into single CHM file, as there shouldn't be any overlap in their contents. It doesn't seem very elegant though.

Coordinator
Nov 17, 2011 at 3:08 AM

As Paul noted, it's not a Sandcastle issue.  You're using conditional compilation which results in a different XML comments file depending on how you build your assembly's project.  If you have two assemblies with their correspondng XML comments files, you can use the Version Builder plug-in to merge the information from both assemblies into one help file.  If I'm not mistaken, the comments elements from both files will be merged for members with a common ID which should give you what you want.

Eric