Since nearly the beginning C# has supported a JavaDoc-like syntax called XML Comments. The compiler extracts these into XML files, one per assembly, which can then be run through a tool that converts them into PDFs, web pages, Help files, etc. The question is, where do you get that tool? It isn’t part of Visual Studio or the .NET Framework.
For a few years the answer was NDoc. The project was going well until the release of .NET 2.0, which added generics. This was a major change to the file format and it would require a significant investment to update NDoc to support it.
The lead developer, Kevin Downs, was working on it but was forced to abandon the effort because of the combination of three factors:
- First was the lack of community support. No developers using the tool were willing to donate time or money to the cause.
- The second factor was a series of anonymous threats made to him and his family. Ostensibly the reason for the attacks was that NDoc 2 wasn’t being completed fast enough. To add insult to injury, whomever made the threats took the time to setup an “email bomb” that repeated the message so many times that Kevin’s email service was suspended.
- Finally there was the announcement that Microsoft would be releasing Sandcastle, their own help file compiler. So like many people, Kevin assumed that Sandcastle would eventually become the de facto tool.
That didn’t really happen because Sandcastle on its own was simply too hard to use. In theory one should be able to simply point the tool at a set of DLLs and XML files, set a few options, and let it run. In practice most developers gave up long before they got anywhere near producing their first batch of documents. So if not for the other issues, NDoc probably would have continued to be wildly popular. But without that option, third party wrappers were created to ease the process.
Sandcastle itself was originally a closed source project being delivered via CodePlex. As many of you are aware, CodePlex was envisioned as a replacement for GotDotNet that would only host open source projects. So after a public outcry in 2008, the source code for Sandcastle was uploaded onto Codeplex under the Microsoft Public License.
Two years later, Sandcastle saw its final official release from Microsoft. That was in June 2010, but it took another two years for Microsoft actually admit that they’ve reached their breaking point and that they intended to walk away from the project.
This is where Eric Woodruff and his Sandcastle Help File Builder comes into the story. In a deal worked out with Darren Parker of Microsoft, Eric would take official ownership of Sandcastle in October of 2012 and merge Sandcastle into the his project. Due to some open legal questions, he wasn’t able to actually claim the Sandcastle site on Codeplex so a fork was created with the original pointing to his project.
As of last month both Sandcastle and Sandcastle Help File Builder are both seeing regular releases, something that Microsoft was unable to achieve during the years they governed the project. Changes in the most recent release include,
- The Sandcastle Tools and Sandcastle Help File Builder have been merged into a single common folder structure. This was necessary to facilitate some of the other changes.
- NOTE: The Sandcastle tools are now installed as part of the Sandcastle Help File Builder and there is no longer a separate installer for them. As such, you will need to manually remove the prior release of the Sandcastle tools. Leaving them installed will not cause any issues as the new release is located in a different folder. However, removing them will avoid any confusion in the future.
- All plug-ins, build components, syntax generators, and custom presentation styles are now MEF components. This makes it much easier to implement project-specific components.
- With the above changes and the implementation of a new Component Path project property, the DXROOT and SHFBCOMPONENTROOT environment variables are no longer needed. SHFBROOT is used to locate all components and the Component Path project property is used to locate project-specific build components. The application data folder can still be used to install components in a common, shared location accessible to all projects.
- Application of the visibility options has been moved from the help file builder into MRefBuilder.
- A new Open XML format and presentation style have been added. See the related help topic for details on its specific requirements and limitations.
- A new preliminary VS2013 presentation style has been added.