This project has moved. For the latest updates, please go here.

Sandcastle Help File Builder (part 2)

Oct 18, 2007 at 10:01 AM
Bertrand,

Can you confirm if the reflection code that AjaxDoc generates can be successfully processed by MS sandcastle compilers (which now it's in a CTP form)? Haven't tried yet but hopefully you already have an answer.

It looks like Sandcastle Help File Builder v1.6 (http://www.codeplex.com/SHFB) still has a problem processing reflection files generated by AjaxDoc. It throws a classic error which is almost nothing: Object reference not set to an instance of an object.
I hope EWoodruff -- the owner of SHFB -- will do a documented test sample to let us know if SHFB really works with AjaxDoc reflection files. The plugin he added for AjaxDoc is a big step forward.

Right now I'm not sure where is the problem: Sandcastle, SHFB or AjaxDoc.

Thx,
Lucian Naie
Oct 18, 2007 at 8:30 PM
Luc1an,
I have successfully used the output from AjaxDoc and the SandCastle compiler to generate a CHM for my JavaScript comments. You have to jump through some hoops, but you can use the Example .bat file sent with SandCastle and modify it to generate the help.

The .xml and .org files that AjaxDoc generate have to be renamed to comments.xml and reflection.org. You also need to make a custom sandcastle.config to exclude VB syntax boxes. Currently you can't generate JScript syntax boxes because of an issue where fields don't specify return data.

I'll try to customize my build to use the MicrosoftAjax assembly, instead of my assembly, and zip that up and make it available, if I can find a place that allows me to post zips.
Oct 19, 2007 at 4:19 PM
There's currently a bug in the plug-in where if you don't add a dummy "Comment Only" XML file to the Assemblies to Document list, it won't get past the "validating assemblies" step. That will be fixed in next week's release. The workaround is to add a dummy file for the time being. The "object not set to an instance of an object" error is caused by the JScript syntax filter (Microsoft's component, not mine). A workaround noted on the MSDN Forum was to remove the VB syntax filter but I don't know if that would work. Turning off the JScript filter would also make it get past that point but of course you wouldn't have and JScript syntax section in the help file.

Eric
Dec 6, 2007 at 1:39 AM
I ended up reflecting the JScript syntax generator, fix the bug and recompile my own syntaxgenerator. This works great and even gives a little better control over the syntax generated (the output of my syntaxgenerator looks at lot more like javascript than what the sandcastle generator comes with).
I can't wait for it to be fixed though - I'd rather use the "real" generator than my own hacked version.
Dec 8, 2007 at 9:26 PM
I fixed the bug in AjaxDoc that caused the JScript syntax generator to fail. You can get a fixed version of the script from the attachment in this work item: http://www.codeplex.com/ajaxdoc/WorkItem/View.aspx?WorkItemId=7889. It also fixes another issue related to namespaces. Once you replace the script and use it with 1.6.0.2 or later of SHFB with the AjaxDoc plug-in you can generate help files using Sandcastle.

Eric