Doc-O-Matic - Documentation Web Help

You are here: More Information > Special Tasks > Documenting without Editor > Topic Structure

Doc-O-Matic 6

Topic Structure

Collapse All

Doc-O-Matic divides topics into logical parts called Sections. You can use these sections to describe different aspects of topics. A section is defined by a unique name and a list of strings used to identify it in topic text. One section can have one or more Starter strings.

If you do not insert Section Starters in front of comment text, the default section is used. Text without starter is assigned automatically to the default section.

Notes

Do not apply character formatting like bold or underlined to section starter strings because this prevents Doc-O-Matic from detecting them properly. If you use a section more than once in a topic section text is concatenated into one text block in the output. Only exception are Additional Information type sections.

Predefined Sections Overview

The following table describes the purpose of each section:

Section Name	Type	Purpose
Description	Standard	Contains the main description of a topic.
Summary	Summary	Contains a summary of the topic description.
Notes	Standard	Used for one or more short notes on a topic, should be short.
Remarks	Standard	For special remarks on a topic, can be fairly long.
Parameters	Parameter Description	Consists of a list of descriptions of each function parameter. For more information about describing parameters, see Parameter Description.
Returns	Return Description	Contains a description of the return value of the function.
Return Value	Return Values	Consists of a list of descriptions of each return value.
Example	Additional Information	For usage examples on the topic being described.
Ignore	Ignored Text	Contains text that is not shown in the output.
See Also	See Also List	Contains a comma-separated list of topic IDs to which links are generated or normal text.
Bugs	Standard	Contains text that describes bugs or problems related to an object.
Internal	Standard	Contains documentation parts, which should only be available to internal team members and not to the general public.
Todo	Standard	Contains text that describes which parts of the object are incomplete and need additional work.
Exceptions	Standard	Contains descriptions of exceptions raised by a function or method during its execution.
Conditions	Standard	Contains descriptions about pre- and post conditions for using certain items, e.g. preconditions for calling a function.
Author	Standard	Contains information about the author(s) of the topic.
History	Standard	Contains information about the development history of an item. This can be used for any topic, but it is usually used for files.
Version	Standard	Contains information about the version of an item, such as version number and compatibility notes for older versions.
Glossary	Glossary Text	Contains the text for the glossary entry of the topic. In the output this section does not appear in the topic.
Source Description	Implementation Description	Contains a descriptive text that is used if the body source code of the object is added to the generated documentation.
Multi Item Glossary	Value Description List	Contains glossary entries and their description. Both columns can be included in a glossary report. In the output this section is not exported by default.
Link List	Named Section	Contains text or links and a name for the section as first string separated by the following text by a comma.

Advanced User Information

Doc-O-Matic can automatically create a summary section from the default section. You can select this option on the Automatic Section Settings page.

Sections can be used for conditional texts. To create different types of documentation from your source create special sections (for example enterprise version) and prevent the export of this section in the normal version. For details, see How can I create different documentation from just one source?.

Additional Information

Starter String Examples
Formatting Examples
Section Example