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

Tables of contents and indexes  

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 specified index. The enumeration is of the form "a, b, c and d".

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

Syntax  

@insert toc
@insert localtoc

@insert {<name>} index
@insert {<name>} index_enum

Miscellaneous content  

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.

Syntax  

@insert author
@insert date
@insert title
@insert see
@insert {<text>} on_empty_section

Example  

@section {} {@id@}
@insert {@id@} decl_inline_doc
@insert {No documentation available} on_empty_section
@end section

Compounds members lists and tables  

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.

Syntax  

@insert {<identifier>} compound_member_list
@insert {<identifier>} compound_full_member_list
@insert {<identifier>} compound_flat_member_list
@insert {<identifier>} compound_inherited_members_count
@insert {<identifier>} compound_inherited_members_list

@insert {<identifier>} ancestors_list
@insert {<identifier>} derived_list

@insert {<identifier>} include_list
@insert {<identifier>} included_by_list

@insert {[<attributes> ...] <types list>} [{<depth>}] [{<scope identifier>}] compound_table
@insert {[<attributes> ...] <types list>} {<grouping type>} [{<depth>}] [{<scope identifier>}] grouped_compound_table

@insert {<identifier>} specializations_table

@insert {<identifier>} struct_table

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.

Examples  

@c insert a table containing all classes
@insert {class} compound_table

@c insert a table containing all first level modules
@insert {module} {1} compound_table

@c insert a table containing all abstract classes which are not deprecated
@insert {!deprecated abstract cxxstruct,class} compound_table

@c insert tables containing main classes and typedefs for each module
@insert {main class,typedef} {module} grouped_compound_table

@c insert tables containing classes for each sub-module of the Bar module
@insert {class} {module} {0} {+Bar} grouped_compound_table

Declarations documentation  

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.

Syntax  

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.

@insert {<identifier>} [{<flags>}] <token>

Valid XHTML 1.0 StrictGenerated by diaxen on Sun Jan 8 22:43:00 2012 using MkDoc