Evolution of Sandcastle
Thanks for all your comments and feedback about the July CTP. I was away last week at a management training and will get back to all your comments. I also received several emails about Sandcastle and have started getting back them. This forum post had some interesting comments and made me write this blog about the evolution of Sandcastle.
Sandcastle builds documentation for any managed class libraries. The only required source files are your assemblies (.dlls or .exes) themselves. For a more complete set of documentation, Sandcastle also supports XML documentation comment files which allow you to provide summaries, remarks, examples, and other content to enhance the documentation. XML documentation comments can be added to your source files ( .cs or .vb or .h/ .cpp). In Visual Studio 2005, the C# (csc.exe), VB (vbc.exe), and C++ (cl.exe) compilers all support XML documentation comments using the /doc:assembly.xml switch. In previous versions of the .NET Framework only C# supported XML documentation comments. For more information on authoring documentation comments, click here.
During VS 2005 ship cycle we wrote Sandcastle to ship .NET Framework documentation for MSDN online and offline libraries. This version of Sandcastle had 2 components cDoc and pDoc.
cDoc
cDoc (comments doc) compiles assemblies (and optionally your comment files) into a cDocML file. The cDocML file contains all of assemblies' metadata and all of XML documentation comments (if any) in an XML format.
pDoc
pDoc (presentation doc) compiles the cDocML file into individual topics organized by namespace, type, and member. pDoc also creates table of contents files, index files, and project files necessary for the HTML Help compilers that will follow.
HHC (HTML Help 1.x Compiler) compiles the pDoc target files into a CHM file and HxComp (Microsoft Help 2.0 Compiler) compiles the pDoc target files into an HxS/HxI pair of files.
The attached diagram illustrates an overview of Sandcastle used for shipping VS 2005 documentation. This version is also used by several teams inside Microsoft for their reference documentation .
After shipping VS 2005, we decided to re-write Sandcastle to improve the perf, scalability and reduce our .NET Framework build time . We started our planning for the new version of Sandcastle (code named “manifold”) in April 2006 with a goal to make this version available externally. The July CTP version of Sandcastle helped us reduce .NET Framework build time from 10 plus hours to 30 minutes. Details on the architecture for the July CTP are available here. We plan to release couple CTPs of this new version before RTW. Also we plan to ship .NET Framework documentation in Windows SDK using this new version .
Anand..
