Share via

Evolution of Sandcastle

  • Article

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..

Sandcastle.png

Comments

  • Anonymous
    August 06, 2006
    Keep up the good work!

  • Anonymous
    August 07, 2006
    I notice you say Sandcastle processes DLLs.  What about EXEs?  It would be nice if Sandcastle were to produce Unix man page style documentation for console apps.

  • Anonymous
    August 07, 2006
    Good eye david. Yes it's .dlls or .Exes and I will modify this post. We support both.

    Anand..

  • Anonymous
    December 05, 2006
    I was thrilled to see Mary Jo Foley , from ZDNet, blog about Sandcastle at her “ Microsoft Codenames

  • Anonymous
    March 12, 2007
    Seit der Auslieferung von Visual Studio 2005 verwenden wir Sandcastle für die Dokumentation des .NET

  • Anonymous
    May 23, 2007
    什么是Sandcastle？这就是Sandcastle的前身。当然，后来发布的Sandcastle由于做了很大的优化，就只要30分钟了。当然，现在的Sandcastle经历了几个CTP版本的测试已经比较成熟了。Sandcastle同NDoc的比较。现在我使用的GUI工具还是Sandcastle Help File Builder（SHFB）。