In writing this, I’m going to assume that you either read my previous article or have ongoing experience with Sandcastle. After using it to autogenerate my documentation I realized a few things.
- My spelling and grammar are horrible in an IDE
- There are a lot of classes that don’t need to be documented (web service proxies, GUI classes)
- MSDN style documentation is nice, but firstname.lastname@example.org probably won’t be as responsive to my custom code as me or the help desk.
This is where Sandcastle Help File Builder comes into play. This tool will build your Sandcastle project for you without requiring a bunch of RegEx magic. When you launch the builder, you will get to choose exactly which assemblies and XML documentation gets included in your Sandcastle project. This is very handy on focusing on what is important and ignoring the autogenerated code that nobody should be touching. In addition, you will be able to customize the output without getting into angle brackets.
- To get started lets fire up SHFB and choose our dlls to document.
- After doing this, click the Namespaces button and deselect all those web service proxy classes that were added
- In the Build section we can set the project settings like FrameworkVersion, Dependencies and Components
- In the Help File section we can customize our build. This is where we will lean on the MSDN style formatting (see the PresentationStyle option), but we will change the Feedback Email, Copyright Info, Project Name, Headers, Footers and all those other things to make the help files match the “approved format”.
- The Paths section lets us customize the build if we installed our components to non-default locations.
- The Visibility section is another great way to focus the documents on the important code. As you are writing your business logic, you will be depending on lower level .NET classes. By default the inherited properties will be included in the documentation. Do you really want to see all of the string methods on your CustomerName property, or do you want to focus on what’s important. This section will allow you to ignore those inherited features.