@insert tag

This tag can be used to insert various content and generated code documentation. The following subsections describe available built-in tokens:

When no built-in token do match, this tag tries to insert content of a macro instead. Some macros are defined in the template.mkdoc file provided when using the bootstrap option.

The insertion does not take place when the @insert tag is encountered but is delayed to a later pass.

See also Processing steps.

The following tokens are available to insert global and local tables of contents:

• toc : This token inserts the global table of contents. Some output formats already provide a generated table of content and may skip sections containing this tag. Sections marked with the T flag appear in the global table of contents.

• localtoc : This token inserts a local table of contents. The local table of contents only contains entries for nested subsections at the current level. Sections marked with the t flag appear in the local toc.

The following tokens are available to insert index content:

• index : This token inserts the specified index.

• index_enum : This token inserts an inline enumeration of entries found in the specified index. The enumeration is of the form "a, b, c and d".

• index_list : This token inserts a list of entries found in the specified index.

The @index tag must be used to populate specified index with entries.

The following miscellaneous content insertion tokens are available:

• author : This token inserts document author as defined in configuration options.

• date : This token inserts document date.

• title : This token inserts document title block.

• see : This token forces write of all pending @see tag and @xsee tag.

• on_empty_section : This token inserts its argument as text if the current section is empty.

Headers, namespaces, classes and modules are compound symbols. Various lists of members can be inserted using tokens described in this section:

• compound_member_list : This token inserts grouped lists of members symbols.

• compound_flat_member_list : This token inserts lists of members including inherited members from hidden base classes.

• compound_full_member_list : This token inserts lists of members including all inherited members.

• compound_inherited_members_count: This token inserts a list of inherited members counts for each visible base classes.

• compound_inherited_members_list: same as compound_inherited_members_count with additional visible members list for hidden base classes.

• ancestors_list: This token inserts a hierarchical list of base classes.

• derived_list: This token inserts a hierarchical list of derived classes.

• include_list: This token inserts a list of included headers.

• included_by_list: This token inserts a list of including headers.

• compound_table : This token inserts a table of compounds of specified types with a short description column.

• grouped_compound_table : This token inserts multiple tables of compounds of specified types with short description. Each table groups entries by specified grouping compound type.

• specializations_table : This token inserts a table of template specializations for the specified class.

• struct_table : This token inserts table of structure fields with nested structures and fields indentation.

When a scope identifier is specified, only sections for compounds within that scope are inserted. The scope may be a C++ scope, module or header.

Maximum recursion depth may be specified, the default value is 0 which means no recursion limit.

See symbol identifiers section for identifiers syntax.

Compounds types list is comma separated.

Valid compound types include header, module, namespace, class, cxxstruct and typedef.

See @foreach tag for attributes list.

Declaration documentation can be inserted using the following tokens:

• prototype: This token inserts the symbol prototype.

• name: This token inserts the symbol name.

• symbol_type: This token inserts the symbol type name.

• parent_name: This token inserts the parent scope name.

• parent_symbol_type: This token inserts the parent scope type name.

• module_name: This token inserts the associated module name.

• decl_location_sentence: This token inserts a sentence which describes symbol declaration location (file, line, expanded macro...).

• decl_module_sentence: This token inserts a sentence which indicates the module associated with the declaraion, if any.

• decl_homonyms_sentence: This token inserts a sentence which give references to alternative declarations with the same identifier, if any. See multiple_symbol_def.

• decl_involved_macros_sentence: This token inserts a sentence which gives the list of macros involved in symbol declaration, if any.

• decl_cpp_condition_sentence: This token inserts a sentence which describes the preprocessor condition associated with the symbol declaration, if any. See Conditional context.

• decl_warn_sentence: This token inserts a sentence which warns about deprecated, experimental and internal declarations.

• decl_override_sentence: This token inserts a sentence with reference to overridden functions in base class, if any.

• decl_access_sentence: This token inserts a sentence which describes associated access specifier used in parent scope.

• decl_qt_sentence: This token inserts a sentence about the symbol being a Qt signal or slot.

• decl_specialization_sentence: This token inserts a sentence about the symbol being a specialization of an other symbol.

• decl_inline_doc: This token inserts the inline documentation attached to the symbol declaration in code comment.

• decl_content: This token inserts a table or code box with content of macro, enum or structure in accordance with current configuration and use of @showcontent tag and @hidecontent tag.

• decl_short_desc: This token inserts short documentation string defined with the @short and @brief tags tag.

• see_related_typedefs: This token adds related type definitions (typedef) as if they were referenced with @see tag.

• decl_synopsis: This token inserts a code box showing appropriate header inclusion directive and symbol prototype.

• inheritance_diagram: This token inserts a class inheritance diagram. Base classes (tree upper part) are not shown if the U flag is used; child classes (tree bottom part) are not shown if the D flag is used.

• inclusion_diagram: This token inserts an header file inclusion diagram. Included headers (tree upper part) are not shown if the U flag is used; Including headers (tree bottom part) are not shown if the D flag is used.

The @alias tag can be used to create an unique name to refer to one of the alternate declarations of the same identifier. See the Symbol identifiers section for identifiers syntax.