Table of contents
Introduction
Since Visual Studio .NET was first released, it has been possible to document your classes directly in code and define the standard documentation sections (such as the summary, remarks, parameter descriptions, etc) which contain the standard tags (such as the member reference, two-column table, list etc). But for us, developers, it was quite inconvenient to fully document our classes and create such long sections as remarks directly in code. The same is true in the case when the documentation is created by a technical writer and the code is created by a developer; it is not quite appropriate for them to work with a single document. The utility we created, DocMounter, is a way to separate the code from the documentation without loss of those conveniences provided by Visual Studio.
DocMounter allows you to easily create MS Visual Studio XML documentation files for your products. These files can be used with your products in Visual Studio (for IntelliSense and in the Object Browser), and you can also use them to get the modern help for your products in one click using such automated help building tools as NDoc and SandCastle.
Creation history
DocMounter was initially created for our internal needs, namely to create full-featured documentation for one of our components. Step by step the tool improved, and finally it has become an easy-to-use application that can be useful for other developers.
Main features
DocMounter allows you to perform the following tasks:
Enter all the standard sections such as summary, remarks, example, see also, etc for classes and their members through a visual interface.
Add tags such as see, code, list, table etc through a visual interface.
Create additional topics using the same syntax as for the classes and their members (XML documentation syntax).
Generate XML documentation files that you can later use to compile a complete documentation with NDoc, SandCastle, or other utility.
Generate HTML files for additional topics (topics not related to a particular class or its members).
Generate a single HTML file from all the additional topics. Later this file may be slightly edited, converted into a DOC, RTF, or PDF format, and used as a manual.
Integrate NDoc, SandCastle, or other utilities to create a compiled HxS help file from XML documentation and additional HTML topics:
Easy Start
Let's build our first help solution with DocMounter.
After starting the application, you will see a start-up dialog like this:
Click the New button in this dialog and then select the library you want to document; a new project will be created.
After the project has been created, you can see the specified assembly's public members in the member tree on the left side of the main form, for instance:
Sequentially select each member of the assembly and enter its descriptions into the sections at the right side of the member tree. Every type of member has its own set of sections, and you can switch among them with the tabs at the top:
You can also use special tags in descriptions. To insert a tag, set the caret to the place you want to insert the tag, click the toolbar button, and specify the tag in the dialog that will appear:
For example if you want to insert a reference to a member, select the See item on the left, select the member to reference to in the tree on the right, and click the OK button.
After you have entered all the necessary descriptions, you can build one of the help types. To build a complete help solution, push the toolbar button. When building is completed, click the toolbar button to view the result.
The output folders are specified in the project properties (the Properties item of the Project main menu item); by default the results are saved to the '10Tec DocMounter Output' folder of the 'My Documents' folder.
Project properties
After creating a new project, you should specify its properties (such as output paths, title, etc). You can do it with the Properties item of the Project menu. Choose this item, and you will see the dialog which allows you to specify all the project properties:
DocSet List [makes sense for building help solution and additional topics only]. In MSHelp 2 every topic can have one or more DocSet attributes. DocSet is an attribute which is used by MSHelp 2 for filtering and searching topics. Here is what Microsoft writes about the DocSet attribute:
The documentation produced for a product or technology needs to be tagged with DocSet, an attribute used in the Help viewer for filtering. It is a convenient way to include a particular set of docs in a filter. Where applicable, apply multiple values per topic. The pre-defined "Visual Basic and Related" filter, for example, looks like this: "DocSet"="Visual Basic" OR "DocSet"="NETFramework" OR "DocSet"="NETFrameworkExtender" OR "DocSet"="DHTML" OR "DocSet"="XML" OR ("DocSet"="MSDN" AND "ProductVers"="kbVBp700")
If you want to enter a few DocSet attributes, separate them with commas. All the entered DocSet attributes will be added to every topic when building help solution or additional topics.
Help Namespace [valid for building help solution and additional topics only]. Allows you to specify the help namespace that your help will be registered in. The help namespace is used by an MSHelp 2 Document Explorer to navigate topics. For example let's look at the address of a topic from .NET Framework documentation:
ms-help://MS.NETDEVFX.v20.en/cpref2/html/T_System_Object.htm
The first part of the address, ms-help, tells the explorer that it should use the ms-help protocol to navigate the file; the second part, MS.NETDEVFX.v20.en, is the namespace where the topic is registered.
When you register your help collection, it is registered with the namespace entered into this field. The namespace consists of several parts. Its first part is the name of your company, the second part is the name of the product the documentation describes, the next part is the version of product, and the last one is the locale code.
How is this namespace used by DocMounter? First of all, when you build the help solution, the resulting HxS (compiled help file) is registered with this namespace to enable its viewing in an MSHelp 2 Document Explorer. Also, the help namespace is used when creating reference links to local members when building additional topics.
System Help Namespace [valid for building help solution and additional topics only]. This is the namespace to use when referencing system members. When a topic is built, all the references to system members are replaced with MSHelp 2 links. These links consist of the help namespace and the a-index of the member. For example, the link <see cref="T:System.Object"> will be replaced with <MSHelp:link keywords="frlrfSystemObjectClassTopic" indexMoniker="!DefaultAssociativeIndex" namespace="ms-help://MS.NETDEVFX.v20.en" tabindex="0">System.Object</MSHelp:link>, where "MS.NETDEVFX.v20.en" is the namespace specified in this field. It means that the link points to the topic with the frlrfSystemObjectClassTopic a-index within the Microsoft .NET Framework v2.0 help collection.
Output. Allows you to specify the output folders for all the types of build. If the XML with Summaries field is empty, the XML document with summary descriptions only is saved to the folders where the assemblies are located.
Describing classes and their members
DocMounter allows you to describe all the public members of an assembly. After you have loaded a project or created a new one, you can see all the members of the project's assemblies in the member tree located at the left side of the DocMounter main window. After you have selected a member in this tree, a set of its description sections appears at the right side of the member tree. Each type of member has its own set of sections. Some sections are common across all the types of members (for example, the Summary section is present in every member type). After compiling the help solution, these sections are gathered into a single topic.
You can type any text into a section description, and it will be transmitted to the output topic directly. In addition, this text may contain special tags. These tags allow you to make references to other types and members, create tables and lists, etc.
The tags are very similar to the tags used in Visual Studio .NET to document classes and their members. You can read more about the tags supported by Microsoft in the following article:
Recommended Tags for Documentation Comments (C# Programming Guide)
In member descriptions, you can use the following Microsoft-supported tags: <see>, <code>, <paramref>, and <list>. (Note: you should not use the <para> tag, as DocMounter will automatically add these tags in place of line breaks.) You can either enter these tags manually or use an automated method provided by the DocMounter visual interface. If you want to insert a tag, move the caret to the place where you want to insert the tag and press the Ctrl+T key combination (or push the Insert tag toolbar button, or choose the Insert Tag item of the Insert main menu item). The Insert Tag form will appear:
On the left side of the form you can see the complete list of tags which are supported by DocMounter. Some of these tags are not supported by Microsoft XML documentation language and are not available to be entered for member description (multi-column table for example). When you select a tag from this list, fields reflecting the tag's parameters appear on the right side of the form. Fill in these fields and then press the OK button. The tag will be inserted into the description.
For example the description text 'This is a reference to the <see cref="T:System.Object" /> member.', which contains a tag, will be compiled into the following text in the output topic:
If you want angle brackets to appear in the text of a documentation, use '<' and '>'. For example '<text in angle brackets>' will be compiled to:
Creating and managing additional topics
In addition to member descriptions, DocMounter allows you to create additional topics that are not related to a specific member. The contents of these topics are not included in the complete XML and XML with summaries, but you can create separate HTML documents for these topics, and these topics are also included in the help solution (the compiled HxS file which is built via an add-in).
To create an additional topic, press the Add button, which is located under the topic tree in the main form of DocMounter. Next to the Add button you'll find the Remove button, which allows you to remove the selected topic. Also you can add, remove, or rename a topic with the context menu that appears when you right-click a topic in the member tree. After creating an additional topic, you can edit it as a usual member, enter plain text, and insert tags.
Building XML help
DocMounter allows you to build XML help documents of two types: XML with summaries and complete XML. The first one stores only the summary sections of the help and is smaller than the latter one. What is it intended to be used for? This XML document is intended to be distributed along with the .NET assemblies that you are documenting, and will be used by Visual Studio IntelliSense. When you are typing code in Visual Studio Code Editor, IntelliSense shows you short descriptions for types and their members. It takes these descriptions from the XML documents that are located in the same folders where your assemblies lie. All the other sections of the XML documentation, if they are present, are not used by IntelliSense, and therefore are not needed in this type of XML document.
The second type of XML documentation, the complete XML, is intended to be used by other utilities such as NDoc and SandCastle to generate complete help files such as HxS (MSHelp 2 compiled help format), CHM etc. This XML documentation contains all the sections of the help (summaries, remarks, exceptions etc).
To build the XML help with summaries, choose the XML Summaries item of the Build main menu item, push the Build XML Summary File toolbar button, or press the Ctrl+Shift+S key combination.
To build the complete XML documentation, choose the Complete XML item of the Build main menu item, push the Build Complete XML Description File toolbar button, or press the Ctrl+Shift+C key combination.
Building additional topics
Since the XML documentation does not support topics that are not directly related to a member, DocMounter allows you to build separate HTML files for additional topics. These HTML files can be later manually included into a help project.
To build the additional topics, choose the Additional Topics item of the Build main menu item, push the Build Additional Topics toolbar button, or press the Ctrl+Shift+T key combination.
Building help solution
DocMounter itself does not allow you to build HxS (MSHelp 2 compiled help format), CHM, and other help files. It only allows you to build XML documentation, which can be later transformed into these formats with such free utilities as NDoc and SandCastle. But it is possible to integrate one of these utilities as an add-in into DocMounter to give you the ability to build help files automatically. If an add-in (a file with the name TenTec.Utils.HelpBuilder.dll) is located in the same folder with DocMounter, you can build a complete help solution in a single step.
At present DocMounter is distributed with only one add-in based on a modified version of NDoc, which was recompiled for the .NET Framework 2.0. This add-in allows you to build MSHelp2 (HxS) files and view them. It requires the Microsoft Help 2 SDK to be installed on your computer. The SDK is a part of the Visual Studio SDK and can be downloaded from the following locations depending on your version of Visual Studio:
For VS 2003: Visual Studio 2003 Help Integration Kit
For VS 2005: Visual Studio 2005 SDK
To create the compiled HxS file, choose the Help Solution item of the Build main menu item, push the Build Help Solution toolbar button, or press the Ctrl+Shift+H key combination.
Building manual
With DocMounter you can not only build separate HTML topics, but you can also create an HTML document that contains all the additional topics. This document is not a complete manual - it is a draft which allows you to create a complete manual. You can change the style of the document, add a table of contents, convert it into another format such as DOC, RTF, PDF etc. For instance, to get a ready-to-print manual, you can open this HTML file in MS Word, add your title and table of contents, and save as a Word document – that's all.
To create the manual, choose the Manual item of the Build main menu item, push the Build Manual toolbar button, or press the Ctrl+Shift+M key combination.
Creating a custom add-in
DocMounter itself does not allow you to build HxS (MSHelp 2 compiled help format), CHM etc help files. It only allows you to build XML documentation, which can be later transformed into these formats with such free utilities as NDoc and SandCastle. But it is possible to integrate one of the utilities as an add-in. The current version of DocMounter allows you to plug only one add-in at a time (it is enough in 99% of cases because if you build help files for your products, you generally use just one such utility).
An add-in for DocMounter is just a class library with the name TenTec.Utils.HelpBuilder.dll which is located in the same folder with the DocMounter. This library should contain a class that implements the IHelpBuilder and IAdditionalTopicHelper interfaces. These two interfaces are described in the TenTec.Utils.IHelpBuilder.dll library, which you can find in the folder where DocMounter is installed.
Currently an add-in based on NDoc is included in DocMounter.
Help files
This article contains only the main parts of the DocMounter manual. The full description of DocMounter can be found in the manual and help included in the installation.
Change log
21 Feb 2007. v1.10, build 0000. Article posted.
20 March 2007. v1.10, build 0001.
- [Fixed] Now DocMounter supports DPI different from normal (96).
- [Fixed] When a library with nested delegates was documented, an error occurred.
