DocProject not reading existing XML comments?

Topics: Bugs, General Questions
Aug 27, 2007 at 3:54 AM
Just installed 1.70RC, and created a new DocProject. But for whatever reason, it is not putting the existing XML comments in the referenced projects on the generated html. The references are just fine and it does create the skeleton documentation based on the members, but their corresponding XML comments are not included in the doc generated.

  • Using VS2005 SP1.
  • XML files reside in the bin\Debug\ directories of the referenced projects.
  • The 'Active Projects' Merge xml documentation = KeepSource

Why could this be happening? Any thoughts?
Coordinator
Aug 27, 2007 at 10:49 AM
Hi,

Could you try changing the Merge settting to its original value? I wonder if maybe you've uncovered a bug with the KeepSource setting...

Thanks,
Dave
Coordinator
Aug 27, 2007 at 10:50 AM
BTW, you could also look in the buildhelp\assembler\Comments folder after the build to see exactly what's in the XML docs. If its what you'd expect then Sandcastle is at fault.

- Dave
Aug 27, 2007 at 6:37 PM
Dave,

I tried changing the Merge settings to its original value ('Overwrite'). That made no difference. Then I changed it back to 'KeepSource'. And after the build, the 'buildhelp\assembler\Comments' folder has an XML file with my code documentation. It's just that that documentation never makes it to the HTML files....

I'm copying the build log below. But before you go over that, here's some info:

I have a Solution called Project1, which has two projects:
1. TestProject (A C# class library) with one class and one method, both with XML documentation.
2. Documentation (A DocProject project). It has reference to TestProject.

Now here's the build log. Let me know if you need more info.

------ Rebuild All started: Project: TestProject, Configuration: Debug Any CPU ------
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Csc.exe /noconfig /nowarn:1701,1702 /errorreport:prompt /warn:4 /doc:bin\Debug\TestProject.XML /define:DEBUG;TRACE /reference:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Data.dll /reference:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll /reference:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Xml.dll /debug+ /debug:full /optimize- /out:obj\Debug\TestProject.dll /target:library Class1.cs Properties\AssemblyInfo.cs

Compile complete -- 0 errors, 0 warnings
TestProject -> C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\TestProject\bin\Debug\TestProject.dll
------ Rebuild All started: Project: Documentation, Configuration: Debug Any CPU ------
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Csc.exe /noconfig /nowarn:1701,1702 /errorreport:prompt /warn:4 /define:DEBUG;TRACE /reference:C:\WINDOWS\assembly\GACMSIL\DaveSexton.DocProject\1.7.0.0_af1a4bab65cc4ece\DaveSexton.DocProject.dll /reference:C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll /reference:"C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\TestProject\bin\Debug\TestProject.dll" /debug+ /debug:full /optimize- /out:obj\Debug\Documentation.dll /target:library Properties\AssemblyInfo.cs

Compile complete -- 0 errors, 0 warnings
Documentation -> C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\bin\Debug\Documentation.dll

Starting help build for Documentation...
Preparing target directory...
Merging xml documentation for TestProject.dll...
Building documentation for Documentation...

Step 1 of 9: Change Directory

Changing current directory from "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\" to "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp"

Step 2 of 9: Execute MRefBuilder

C:\Program Files\Sandcastle\\ProductionTools\MRefBuilder /config:"C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\Presentation\Style\Configuration\MRefBuilder.config" /out:reflection.org /internal- /dep:"C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\mscorlib.dll" "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\TestProject\bin\Debug\TestProject.dll"

MrefBuilder (v2.2.63000.2)
Copyright c Microsoft 2006
Info: Loaded 1 assemblies for reflection and 1 dependency assemblies.
Info: Wrote information on 1 namespaces, 1 types, and 2 members

Step 3 of 9: Execute XslTransform

C:\Program Files\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Sandcastle\\ProductionTransforms\ApplyPrototypeDocModel.xsl" reflection.org /xsl:"C:\Program Files\Sandcastle\\ProductionTransforms\AddFriendlyFilenames.xsl" /out:"reflection.xml"

XslTransform (v2.2.63000.2)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Sandcastle\\ProductionTransforms\ApplyPrototypeDocModel.xsl'.
Info: Applying XSL transformation 'C:\Program Files\Sandcastle\\ProductionTransforms\AddFriendlyFilenames.xsl'.

Step 4 of 9: Execute XslTransform

C:\Program Files\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Sandcastle\\ProductionTransforms\ReflectionToManifest.xsl" "reflection.xml" /out:manifest.xml

XslTransform (v2.2.63000.2)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Sandcastle\\ProductionTransforms\ReflectionToManifest.xsl'.

Step 5 of 9: Execute XslTransform

C:\Program Files\Sandcastle\\ProductionTools\XslTransform /xsl:"C:\Program Files\Sandcastle\\ProductionTransforms\CreatePrototypeToc.xsl" "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp\reflection.xml" /out:"toc.xml"

XslTransform (v2.2.63000.2)
Copyright c Microsoft 2005-2006
Info: Applying XSL transformation 'C:\Program Files\Sandcastle\\ProductionTransforms\CreatePrototypeToc.xsl'.

Step 6 of 9: Copy File

Copy "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp\reflection.xml" to "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp\assembler\reflection.xml" and overwrite.

Step 7 of 9: Change Directory

Changing current directory from "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp" to "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp\assembler"

Step 8 of 9: Build Assembler {sandcastle.help1x.config}

Info: Instantiating component.
Info: Loading data file '..\..\Presentation\Style\transforms\skeleton.xml'.
Info: Instantiating component.
Info: Searching for files that match 'reflection.xml'.
Info: Searching for files that match 'C:\Program Files\Sandcastle\\Data\cpref_reflection\*.xml'.
Info: Indexed 149248 elements in 105 files.
Info: Instantiating component.
Info: Instantiating component.
Info: Loading subcomponents.
Info: Instantiating component.
Info: Loaded 1 subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Loaded 3 syntax generators.
Info: Instantiating component.
Info: Searching for files that match 'comments.xml'.
Info: Searching for files that match 'C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\*.xml'.
Info: Indexed 75461 elements in 65 files.
Info: Instantiating component.
Info: Loading subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Instantiating component.
Info: Loaded 2 subcomponents.
Info: Instantiating component.
Info: Instantiating component.
Info: Loading shared content file '..\..\Presentation\Style\content\shared_content.xml'.
Info: Loading shared content file '..\..\Presentation\Style\content\reference_content.xml'.
Info: Loading shared content file '..\..\Presentation\Style\content\syntax_content.xml'.
Info: Loaded 162 shared content items.
Info: Instantiating component.
Info: Indexed 149248 reference link targets.
Info: Instantiating component.
Info: Building topic R:Project
Info: Building topic N:TestProject
Info: Building topic T:TestProject.Class1
Info: Preparing to query MSDN topic URL web service.
Info: Building topic M:TestProject.Class1.#ctor
Info: Building topic M:TestProject.Class1.Test

Topics processed: 5

Step 9 of 9: Copy Directory

Deep move "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\buildhelp\assembler\Output\html" to "C:\Documents and Settings\<UserName>\My Documents\Visual Studio 2005\Projects\Project1.root\Project1\Documentation\Html".

Build step execution complete.

Verifying output...
Done.

Successful Steps: 9 of 9
Failed Steps: 0

Documentation help build complete.

Coordinator
Aug 27, 2007 at 7:10 PM
Hi,

Thanks for the info. If you look at step #8 (build assembler) you'll see the following line:


Info: Searching for files that match 'comments.xml'.

This indicates to me that the Presentation\Style\Configuration\sandcastle.help1x.config file was not properly updated when it was imported into the new DocProject by the New Project Wizard.

The sandcastle.config file that is installed by Sandcastle for the selected presentation style is automatically updated based on an XPath expression to change comments.xml to Comments\*.xml, for obvious reasons. I've never heard of this update failing however.

First, do you have the latest version of Sandcastle installed? That would be the June 2007 CTP.

If so, have you made any mods to the installed sandcastle.config file?

In this case you can open DocProject's config file (commonly found at, C:\Program Files\Dave Sexton\DocProject\DaveSexton.DocProject.dll.config; do not confuse it with DocProject.exe.config however) and update the transformation near the bottom of the file to make the correct change to the config file when it's imported. If you need assistance please let me know.

- Dave
Aug 28, 2007 at 1:48 AM
Dave,

You got it! The configuration files copied were from Sandcastle March 2007 CTP. This was probably because the doc project was created before June 2007 CTP was installed... Removed the doc project and recreated a brand new using the wizard and everything seems to be working fine. Thanks very much!

However, I wonder if it would make sense for your code to not copy (at least by default) the config files from Sandcastle to the project's folder when the project is created and instead, read those from Sandcastle's directory itself as/when the doc is being built. It would be a pain to have to delete and recreate the doc project each time there's a new version of Sandcastle and I want to take advantage of its new features...

Thanks again!
Deepak
Coordinator
Aug 28, 2007 at 3:24 AM
Hi Deepak,


You got it! The configuration files copied were from Sandcastle March 2007 CTP

Glad to hear that it works now :)


However, I wonder if it would make sense for your code to not copy (at least by default) the config files from Sandcastle ...

There are several problems with this approach, although if you want you can update the Presentation Path option in your DocProject to point to one of Sandcastle's installed presentation folders, but I recommend against it!

For one thing, you couldn't just use the installed sandcastle.config without also using all of the xsl transformations and other files on which it depends. This means that if you wanted to change something on a per-project basis you couldn't without inadvertently affecting every other DocProject and DocSite on your computer. In this case you wouldn't have a local Presentation folder, which means that the API Topic Management dialog, for example, would have to save its state in Sandcastle's installation directory!

As for the pain of having to recreate your DocProject each time a new version of Sandcastle is released, I can certainly understand how that's undesirable, but that's just one reason why DocProject is only a release candidate and not RTW ;) Once Sandcastle is no longer CTP and DocProject is RTW, you won't have that problem any longer even with the current architecture.

I appreciate the feedback though, thanks.

- Dave
Aug 28, 2007 at 4:13 AM
Edited Aug 28, 2007 at 4:27 AM
Cool.

As to the feedback, if docProject could also offer hashcode as an option for the html file names, that would be great. Currently you can either have the a GUID (which, by its definition, probably changes every time you build?) or a "Friendly" name, which can get really long. A hashcode could give a middle ground (i.e. it won't change, and won't be too long) and would be really helpful for those who have to link individual doc pages from other external apps/pages.

Very good project, nevertheless. Thanks for your contribution to the community!
Coordinator
Aug 28, 2007 at 2:32 PM
Hi Deepak,

That's a good suggestion, but I believe that Sandcastle is already generating a hashed value, not a true GUID.

A search on the web returned a discussion for the SHFB project here on CodePlex. Check out Eric's response:

Sandcastle Help File Builder, Output Deleted When New Build Starts
http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=13263

For a particular topic the name should be the same each time it's generated as long as the topic's ID is the same.

I'll post a question in the forums just to be sure. But if that's not the case, you should request this feature of Sandcastle, not DocProject.

Thanks,
Dave
Coordinator
Aug 28, 2007 at 4:15 PM
Hi Deepak,

It turns out that the GUID file names are acutally just MD5 hashes of the topic ID. So, if a topic's name isn't changed then you'll get the same GUID for the file name each time it's generated.

Since the topic names are generated automatically, I doubt you'll have to worry about them changing, so GUID names should be fine for your needs.

- Dave
Aug 28, 2007 at 5:11 PM
Dave,

Thanks for the excellent follow through on this. If I can count on the "GUID"s to not change over builds for a given topic ID, then that works for my needs.

-Deepak