Add Root

Creates a new topic at the root level.

Add Child

Creates a new topic as a child of selected topic.

Delete button

Deletes selected topic and all of its subtopics if any.

Up and down buttons

Move selected topic up or down in the TOC. You can also move the topic with drag & drop.

Each topic has a set of properties. Properties of selected topic are shown on the right side. A topic is of one of the three types:

1. Topic or chapter with text

This topic contains an assigned text that is shown when you click this topic in TOC. If the topic contains sub-topics, it is called a chapter. Otherwise it is called just a topic.

2. Topic or chapter without text

This is a topic or chapter which has no text. When you click on it in the TOC, no generated topic is shown. It works in two ways. Normally, you don't assign any external file or URL with such a topic. In this case it only serves as a chapter name for sub-topics. But you can also define a link to an external file or URL. In such a case, when you click on the topic, it will open an external file or a web URL. Of course, this will only work if you generate HTML or CHM output.

3. Placeholder for namespaces

This is not a real topic. It is only a placeholder for generated API for your namespaces. Each documentation should contain at least one such placeholder so that the API reference be included in it. Usually, you have one placeholder where all your API reference is placed. But you can create unlimited number of placeholders. Placeholders are shown with green color and [NAMESPACES] text in the left tree.

Topic title

This is the title shown in topic header and TOC. Title is ignored for namespaces placeholders.

Unique ID

Each topic, except for namespaces placeholders, has its own unique ID. Default ID is generated from the title but you can change it as you like. The ID can only contain alphanumeric and underscore characters. The ID is used in <see> and <seealso> links pointing to the topics. The cref parameter has form Y:ID. For example, you can create a link like <see cref="Y:overview">See overview</see>. You can use such links in other topics and also in code element comments, e.g. in class remarks. WYSIWYG comment editor supports creating and editing the links to custom topics so you don't have to remember link syntax and topic IDs.

Show as default topic

When this is checked, the topic is automatically shown when you open generated documentation. This is usually Overview or Introduction topic. This applies to CHM and HTML output formats. You can only have one default topic.  Default topic is shown with blue color in the left tree.

Target file or URL

Specifies a target file or URL for a topic or chapter without text. If left blank, the topic will not open anything and it serves as a chapter for sub-topics. Or you can specify any URL or an external file, such as an HTML page, TXT file or anything you need.

Namespace full names(s)

If the topic type is a placeholder for namespaces, you can specify which namespaces should appear at this place. Usually, you want all namespaces so you leave this field blank. Or you can use standard regular expressions to select particular namespace(s). Creating multiple placeholders with various filters, you can split your API reference into several parts that are placed at various places in the TOC. Remember that matching is performed with namespace full name. For example, if you want to include all namespaces starting with "Helixoft.Demo.", enter the following:

Helixoft\.Demo\..*

There's also Test button which opens a regex tester so you can immediately test and modify your pattern.

The topic content is defined the same way you define documentation for code elements. That means you use the same XML comments with tags such as <summary>, <example>, <b>, <see>, etc. Of course, you don't use XML comment prefix ''' or ///. So you can easily format your text, insert links, pictures, tables, lists, etc. There are two ways of editing topic text.

Editor button

Opens WYSIWYG editor where you can edit the topic very comfortably.

Edit source button

Opens simple text editor where you can edit directly XML source code of the topic.

Custom Topics Overview