Comments with "include" tag not included

Topics: Developer Forum, User Forum
Jan 19, 2009 at 11:24 AM
Not sure if this has been discussed before (sorry if it has, I didn't find anything).  I am not sure if this is a Sandcastle compiler issue/problem, a Help File Builder issue/problem or just my understanding of the many options and how to use them, but if I use the <include> tag in my XML comments the final compiled help using Sandcastle does not have the included content.  When I check the generated XML documentation file after building my C# projects, the content is in this file.  Both the .dll and generated XML comment file are included in the SHFB UI when I build the help project though, the "include" information is not in the final documentation.  I am filtering out namespaces and object and I dscovered that if I do not specify that the .dll is avalable (only the XML documentaton file) then I do not get any documentation for that .dll, almost as if its not reading the XML documentation file and is only going off reflection, this may be a separate or unrelated issue though. 

Any help or pointers would be apreciated.

Thanks,
Kevin F.
Coordinator
Jan 19, 2009 at 5:47 PM
Is the <include> in the XML comments file or are the target comments imported by the include in the XML comments file?  You should see the target comments, not the <include>.  If you see the <include>, it didn't work and it's usually preceded by an XML comment stating that it failed.  If you filter out an entire namespace, it won't appear in the help file at all.  Likewise if you filter out an entire class.  If you haven't done so already, go into the APIFilter property and reset it so that everything is included.  Also, go into the Namespace Comments editor and make sure that all namespaces are checked so that they show up.  Then do a build and see if all the expected comments are showing up.  It could be that you're turning off a namespace or a class in the filters and they are being excluded.

Eric
Jan 19, 2009 at 6:17 PM
Hi Eric, the target comments are indeed in the VS generated XML comments file.  The filters I have set are not excluding the objects and methods that I am trying to comment, in other words , everything I expect shows up in the final HTML help file, and everything I have "unchecked" does not show up.  What I did was write the XML comments directly in the source first, generated the help to verify that everything appeared as expected, then moved the comments into an external file and used the <include> XML comment tag and referenced the moved comments, I then built the project and verified that the XML documentation file included the comments, then ran the Sandcastle GUI build.  The objects all appear in the final output but now all the comment sections have the big red "no comments available" type message.  I even mixed the comments with some embedded into the code as usual and others "included" and only the embedded comments got pulled in.  Now its very possible that I have misunderstood how to use the "include" tag and thats why its not working (documentation is rather thin in this regard) but I almost get the impression that Sandcastle is re-generating the comments and ignore the <include> tag. 

One problem I have with Sandcastle in general (or the GUE), again maybe my understanding of it is not as good as it could be, is in my case I want to generate API documentation for a few objects in a single namespace and assembly but I cannot seem to do this unless I also include all its dependant assemblies (which in my case is a couple of dozen with twice that number of namespaces).  Sorry, thats just a user rant :)

Thanks,
Kevin F.
Coordinator
Jan 19, 2009 at 8:15 PM
Edited Jan 19, 2009 at 8:21 PM
Hi Kevin,

If I'm understanding you correctly, you're putting the <include> in an XML comments file.  If so, that won't work as the <include> tag is only expanded by the compiler.  The <include> must only appear in source code XML comments.  Also, did you include the XML comments file generated by the compiler as a documentation source (add it to the XmlCommentsPath property of the assembly in v1.7 or to the Documentation Sources project node in v1.8).  If you still can't get it to work, perhaps you can send me a small example that demonstrates the problem you are having.  My e-mail address is in the About box in the GUI and in the footer of the pages in the help file.

Regarding dependency assemblies, they should go in the Dependencies property (v1.7 or earlier) or in the References project node (v1.8).  That lets the MRefBuilder tool find them and add base class info but keeps their content out of the help file.  See the Getting Started sections in the help file as they cover the basics.  The Getting Started topics in the v1.8 help are a bit more comprehensive (http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/b772e00e-1705-4062-adb6-774826ce6700.htm).

Eric