.NET 1.1+Documenting Namespaces with Sandcastle Help File Builder
When documenting code libraries it is important that namespaces are described. XML documentation comments do not support the addition of summary information for namespaces. However, this extra information can be added using Sandcastle Help File Builder.
Namespace Documentation
When you are creating documentation for your software using XML documentation comments, you should usually add summaries and detailed information for all of your types and their members. Unfortunately, you cannot add summary information for the namespaces defined in your projects. If you try, you will find that they are not included in the outputted XML and so cannot be transferred to the final help files. When compiling the documentation with Sandcastle Help File Builder (SHFB), you will see a placeholder for each namespace, with text similar to that shown below:
[Missing <summary> documentation for "N:MyNamespace"]
SHFB gets around the limitation by allowing you to manually add a summary to each namespace. This summary is stored within the SHFB project so that you do not need to recreate it each time you build the documentation.
To edit the namespace summaries, expand the Summaries section within the Project Properties tab in SHFB. You will see a setting named, "NamespaceSummaries", which initially shows the value, "(None)". Click the setting to select it and a button showing an ellipsis symbol (...) appears. Click this button to display the Namespace Summaries dialog box, pictured below:
When the dialog box first loads you must wait for a few moments whilst your project is reflected over and the contained namespaces identified. Once this process is complete, a list of discovered namespaces is displayed in the list at the left of the dialog box. Click one of these and the assembly name is shown in the box to the right and the current summary for the selection is displayed in the textbox at the bottom of the dialog box. This summary is blank until first provided. Add the summary for each namespace that requires one and click the Close button to complete the process. You should save the SHFB project to retain the descriptions.
Once the dialog box is closed, simply rebuild the help file project. After compilation, you will find that the namespace summary information is present in the generated help file.
4 April 2012