Use Sandcastle to document .Net Assemblies
If you already have Sandcastle then Uninstall it before running this, and check that DXROOT is not stuck as a user environment variable. The new Sandcastle puts DXROOT as a system environment variable, so remove any user DXROOT if it exists.
Download the latest Sandcastle Help File Builder Guided Installer. Unzip it and find SandcastleInstaller.exe.
It installs documentation and two products -- Sandcastle and Sandcastle File Builder. Sandcastle is a command line tool. Sandcastle File Builder is an IDE on your [All Programs] menu.
Accept everything from the Install, except Microsoft Help 2 Compiler. You can bypass that one. The installation does not auto-advance. You must keep pressing [Next] to continue. At the Completion page make a note of the documentations. It is on your workstation (probably at Documents). Click [Reboot].
To generate docs, setup Visual Studio 2010 so it will generate MAML. I created a new console application. At Project go to [properties]. On [Build], check telling it to make XML. Also enter compiler option "/doc". Watch Setting up Visual Studio 2010 so it generates MAML. To test just build the project and look to .\bin\Debug for a new XML file. You may have to create a class (or use test.cs that sandcastle provides). My file is ConsoleApplication11.XML. The recommended naming is by assembly name.
Open Sandcastle File Builder GUI from start, programs and generate help. There are four possible file types. I am doing Web Documentation. Watch Building a Help File Project.
1: HTML Help 1 files are standalone help files with a .chm extension. This is the oldest help file format and these files can be viewed on any system without any special viewers.
2: The Microsoft Help 2 format produces help files with a .HxS extension. It’s used by Microsoft Visual Studio 2008 and earlier. The Help 2 compiler is available only as part of Visual Studio 2008 or earlier.
3. Microsoft Help Viewer: This is the latest help file format and produces help files with a .mshc extension that is used with Visual Studio 2010 and later. They do not require a compiler. Instead, the help content is compressed into a ZIP-format archive file. Third-party build tools for Sandcastle will provide the support necessary to create the help archive and its related configuration file.
4. WebSites produces HTML files.
More! Visual Studio will now nudge you to add documentation for any publicly visible methods. Add “///” to generates default tags <summary></summary>.
/// <summary>
/// This class performs an important function
/// </summary>
public class MyClass{}
There are many tags that will display different sections of the help. See .\My Documents\SandcastleMAMLGuide\Help\SandcastleMAMLGuide.chm [Conceptual Content File Types] [Topic File][Samples]
