Click here to Skip to main content
Click here to Skip to main content
Go to top

DocMounter Help File Builder

, , 21 Mar 2007
Rate this:
Please Sign up or sign in to vote.
Tool for creating MS Visual Studio XML documentation files. These files can be used for Visual Studio Intellisense, and to create help files via tools such as NDoc and SandCastle.

Screenshot - DocMounter.gif

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:

  1. Enter all the standard sections such as summary, remarks, example, see also, etc for classes and their members through a visual interface.

  2. Add tags such as see, code, list, table etc through a visual interface.

  3. Create additional topics using the same syntax as for the classes and their members (XML documentation syntax).

  4. Generate XML documentation files that you can later use to compile a complete documentation with NDoc, SandCastle, or other utility.

  5. Generate HTML files for additional topics (topics not related to a particular class or its members).

  6. 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.

  7. Integrate NDoc, SandCastle, or other utilities to create a compiled HxS help file from XML documentation and additional HTML topics:

    Screenshot - DocMounterOutput.gif

Easy Start

Let's build our first help solution with DocMounter.

After starting the application, you will see a start-up dialog like this:

Screenshot - StartupDialog.gif

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:

Screenshot - MembersTree.gif

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:

Screenshot - Sections.gif

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 Screenshot - InsertTagToolbarButton.gif toolbar button, and specify the tag in the dialog that will appear:

Screenshot - InsertTag.gif

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 Screenshot - BuildHelpSolutionToolbarButton.gif toolbar button. When building is completed, click the Screenshot - ViewHelpSolutionToolBarButton.gif 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:

Screenshot - ProjectProperties.png

  • 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:

Screenshot - InsertTag.gif

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:

Screenshot - CompiledTextWithTag.gif

If you want angle brackets to appear in the text of a documentation, use '&lt;' and '&gt;'. For example '&lt;text in angle brackets&gt;' will be compiled to:

Screenshot - TextInAngleBrackets.gif

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.

    1. [Fixed] Now DocMounter supports DPI different from normal (96).
    2. [Fixed] When a library with nested delegates was documented, an error occurred.

License

This article, along with any associated source code and files, is licensed under The GNU General Public License (GPLv3)

Share

About the Authors

10Tec

Ukraine Ukraine
No Biography provided
Group type: Organisation

2 members


Sergey Gorbenko
Software Developer (Senior)
Canada Canada
No Biography provided

Comments and Discussions

 
GeneralProblems with Intellisense in VS 2008 PinmemberCashels14-Nov-10 21:11 
GeneralRe: Problems with Intellisense in VS 2008 Pingroup10Tec14-Nov-10 21:37 
GeneralDocMounter 2.0 is out Pingroup10Tec3-Nov-10 21:43 
GeneralRe: DocMounter 2.0 is out PinmemberAhmed Charfeddine4-Nov-10 1:42 
General!! Announcement /April-2010/: DocMounter v2 with extended functionality and based on SandCastle comes out soon Pingroup10Tec9-Apr-10 3:30 
GeneralExcellent and one question PinmemberMarcos Meli7-Apr-10 17:13 
GeneralRe: Excellent and one question PinmemberSerge Gorbenko7-Apr-10 21:01 
GeneralRe: Excellent and one question PinmemberMarcos Meli8-Apr-10 5:41 
GeneralVERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member PinmemberMamadou Bah7-Apr-10 8:34 
AnswerRe: VERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member PinmemberSerge Gorbenko7-Apr-10 10:00 
GeneralRe: VERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member PinmemberMamadou Bah7-Apr-10 11:36 
GeneralRe: VERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member PinmemberSerge Gorbenko7-Apr-10 20:59 
GeneralRe: VERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member PinmemberMamadou Bah8-Apr-10 7:47 
GeneralRe: VERY URGENT:Error when adding Exceptions to a member or adding 'SeeAlso' to a member Pingroup10Tec9-Apr-10 1:45 
GeneralBug Fix PinmemberJeremy Beckham8-Mar-07 14:49 
GeneralRe: Bug Fix PinmemberSerge Gorbenko14-Mar-07 5:25 
GeneralQuestion Pinmemberrtsang6-Mar-07 10:54 
GeneralRe: Question PinmemberSerge Gorbenko6-Mar-07 20:25 
GeneralSeems to be very helpful PinmemberEdWin14091-Mar-07 10:48 
GeneralReading existing XML Pinmemberkennym_dk1-Mar-07 1:00 
GeneralBuild Pinmemberapessotto27-Feb-07 2:55 
GeneralRe: Build PinmemberSerge Gorbenko27-Feb-07 3:23 
GeneralRe: Build Pinmemberapessotto27-Feb-07 8:08 
GeneralRe: Build PinmemberHardy19-Mar-07 9:25 
GeneralPerformance PinmemberMarc Leger21-Feb-07 7:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.140916.1 | Last Updated 21 Mar 2007
Article Copyright 2007 by 10Tec, Sergey Gorbenko
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid