Predefined Sections and Section Types

The following table shows all predefined sections in Doc-O-Matic and suggests how to write well-formatted source code comments. In general, if you are writing a user manual you can freely decide which sections you want to use. However, not all section types are processed in the same way in the output formats.

Predefined Sections

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

Section Types

This table shows all section types that you can use in your project.

Section Type	Meaning	Output - default settings
Standard	Text of your Help topic.	Appears on the topic page. Section name appears as heading unless the section is the first section in the topic.
Parameter Description	Text contains descriptions of function parameters.	Appears on the topic page. Can be formatted as list of parameter names and descriptions or as two-column table. As parameter names the name or the full declaration can be shown. For details, see Parameters, Return Values and Members Section. You can not apply character formatting to parameter names.
Return Description	Text contains the description of a function return value.	Appears on the topic page. Section name appears as heading unless the section is the first section in the topic.
Return Values	Text contains descriptions of return values.	Appears on the topic page. Can be formatted as list of return values and descriptions or as two-column table. For details, see Parameters, Return Values and Members Section. You can not apply character formatting to values.
Additional Information	Text contains additional information to the topic.	Appears on the topic page and on a separate page in Help systems. Headings following the section heading as very first string are used as title for the separate page in Help systems and as section heading. When no heading follows the section heading, the section name is used as section heading or page title. When you use this section more than once in a topic section, headings are automatically numbered (Example 1, Example 2....). For details, see Additional Information Sections (Examples).
Summary	Text contains a brief description of the purpose of the item being described.	Appears on the topic page. Doc-O-Matic can create this section automatically from the first sentence of your default section. For details, see Automatic Sections
See Also List	Text contains a list of topic IDs used as see also list or normal text.	Topic IDs are automatically linked. Topic IDs appear as link text. The see also link lists can appear inline, on a separate page (HTML Help systems) or in a pop-up window (Windows Help). For details, see See Also and Named Section.
Ignored Text	Text that shall be ignored by Doc-O-Matic.	Text does not appear in the output.
Glossary Text	Glossary description for the topic title.	Text does not appear in the topic. But can be used for creating reports. For more information about creating your glossary and other reports, see Creating Reports.
Implementation Description	Text in this section is used for the description of the body source code of functions and files.	For details, see Code Presentation.
Named Section	Text with no special meaning. Very first string separated from the text by a comma names the section.	The very first string is used as section heading, the comma separated text as text of the section. For details, see See Also and Named Section.
Value Description List	Text contains value lists	Can be formatted as list of values and descriptions or as two-column table. You can not apply character formatting to values. You can use values and descriptions for creating reports. For details, see Creating Reports.

Automatically Created Sections

These are sections that Doc-O-Matic automatically creates depending on the items available in the documentation.

Section (Default)	Section (VS-Template)	Type	Settings Page
Body Source	Body Source	Symbol Body Source	Body Source Code
Class Hierarchy	Inheritance Hierarchy	Class Hierarchy	Local Class Hierarchy
Container	Container	Symbol Container	Container Section Options
Pascal, C++, C#, Visual Basic, PHP, MATLAB, JavaScript, IDL, Java	Pascal, C++, C#, Visual Basic, PHP, MATLAB, JavaScript, IDL, Java	Syntax	Multi Language Syntax, Syntax Highlight, Section Format (HTML) for tabbed section feature
Links	Links	Topic Links	Navigation Links Format (HTML)
Reports	Reports	Reports	Section Format (HTML, PDF, RTF), Table Layout
Overload List	Overload List	Overload List	Content Options
Navigation	Navigation	Topic Navigation	Section Format (HTML, PDF, RTF), Table Layout, Content Options
Members	Members	Member Description Section	Section Options