Generators

MrDocs uses a generator to convert the extracted symbols into documentation. MrDocs supports multiple output formats that can be specified via the generate option:

The generate option can be used to specify the output format:

# ...
generate: adoc
# ...

Three output formats are supported:

Format Description

adoc

AsciiDoc format.

html

HTML format.

xml

XML format.

The corpus of symbols is provided to the generator responsible for converting these symbols into the desired output format.

The xml generator is used as an intermediary format for other tools or for testing purposes. Users can write their own tools to process the XML output and generate custom documentation.

The adoc and html generators use templates to generate the documentation. These templates can be customized to change the output format and style.

Asciidoc is a text-based format that is easy to read and write. It can also be converted to other formats such as HTML and Markdown.

HTML can be generated directly with the html format.

Choosing the Right Generator

The scatter plot below illustrates the available output formats for MrDocs, along with hypothetical solutions, in terms of redundancy and convenience.

Output Formats Scatter Plot

  • Redundancy: The amount of duplicated or unstructured information in the output format. Lower redundancy is generally preferred for post-processing, while higher redundancy can allow the output to use formats that are easier to use directly.

  • Convenience: Reflects how readily the output format can be used without requiring additional tools or steps.

Although Clang can generate and print an Abstract Syntax Tree (AST) directly for a Translation Unit (TU), it is not the most convenient format for generating documentation:

  • It does not provide the AST in a format that’s easy to process.

  • Equivalent symbols can be redeclared multiple times in the same translation unit and across translation units.

  • The documentation for equivalent symbols also needs to be unified.

The scatter plot shows the following output formats supported by MrDocs:

  1. XML: Aggregates all symbols and their documentation in a format that is straightforward to process. It’s suitable for advanced use cases involving custom post-processing tools.

  2. Asciidoc: Similar to HTML in convenience, Asciidoc files can be easily converted to HTML and multiple other formats with backends.

  3. HTML: Generates output that is directly usable in a variety of contexts, such as web pages or documentation systems.

The Asciidoc and HTML generators also support Custom Templates to change the output format and style. This forms another possibility in the trade-off between redundancy and convenience.

The best trade-offs, represented by the line passing through the generators, indicate the optimal solutions in terms of redundancy and convenience. Solutions on this line balance these goals effectively. Dots in the background represent other potential formats that do not lie on the front of best trade-offs, as they fail to optimize either redundancy or convenience compared to the available generators.

Generator Templates

MrDocs attempts to support various alternatives for customizing the output format and style without complex workflows to post-process XML output. The adoc and html generators use Handlebars templates. These templates can be customized to change the output format and style of the documentation.

The templates used to generate the documentation are located in the share/mrdocs/addons/generator directory. Users can create a copy of these files and provide their own addons directory via the addons option in the configuration file or via the command line.

addons: /path/to/custom/addons

Each symbol goes through a main layout template in the <addons>/generator/<generator>/layouts/single-symbol.<generator>.hbs directory. This template is a simple entry point that renders the partial relative to the symbol kind.

The partials are located in the <addons>/generator/<generator>/partials directory. It typically contains the following files and subdirectories:

  • symbol: A generic partial for rendering symbols.

  • location: Partials for rendering location objects.

  • symbol: Partials for rendering Symbol Objects.

  • template: Partials for rendering Template Info Objects.

  • type: Partials for rendering Type Info Objects.

  • markup: partials for rendering markup elements such as lists, tables, and code blocks, in the output format.

Please refer to the Document Object Model Reference for more information on each type of object.

Partials common to all generators are available in the <addons>/generator/common/partials directory. The common partials are loaded before the generator-specific partials, which can override any common partials.

The multipage generator renders the layout multiple times as separate pages for each symbol. The single-page generator renders the layout multiple times and concatenates the results in a single page.

Each time the generator encounters a symbol, it renders the layout template with the symbol data as the Handlebars context. The layout template can include other partial templates to render the symbol data. These partials are available in the <addons>/generator/<generator>/partials directory.

The Document Object Model (DOM) for each symbol includes all information about the symbol.One advantage of custom templates over post-processing XML files is the ability to access symbols as a graph.If symbol A refers to symbol B, some properties of symbol B are likely to be required in the documentation of A.All templates and generators can access a reference to B by searching the symbol tree or simply by accessing the elements A refers to.All references to other symbols are resolved in the templates.

Document Object Model Reference

The Document Object Model (DOM) is a tree structure that represents the symbols extracted from the source code.The DOM is used by the generator to render the documentation.

Top-Level Fields

The top-level object in the DOM is the context for a template.The top-level object has the following properties:

Property Type Description

symbol

Symbol Object

The symbol being rendered.

config

Config Object

The configuration object.

Symbol

The Symbol object represents a symbol extracted from the source code.The symbol being rendered is available in the symbol object in the Handlebars context.The symbol object has the following properties:

Property Type Description

id

string

A unique identifier for the symbol.

name

string

The nonqualified name of the symbol.

kind

string

The kind of symbol. (e.g., class, function, variable)

access

string

The access level of the symbol. (e.g., public, protected, private)

implicit

string

Whether the symbol was implicitly extracted as a dependency.

namespace

Symbol Object[]

The namespaces of the symbol.

parent

Symbol Object

The parent namespace of the symbol.

doc

Any

The documentation for the symbol.

Handlebars generators extend each symbol with the following fields:

Property Type Description

url

string

The URL of the symbol. If the documentation is a single page, this is the anchor link to the symbol starting with #. If the documentation is multipage, this is the path to the symbol starting with /.

anchor

string

The anchor link to the symbol. This is used for section IDs in the documentation.

The Symbol object has additional properties based on the kind of symbol. The following table lists the additional properties for symbols that contain information about their scope (such as Namespaces and Classes):

Property Type Description

members

Symbol Object[]

The members of that scope (e.g., member functions, namespace symbols).

overloads

Symbol Object[]

Same as members, but groups overloaded functions as unique symbols of kind overload.

Symbol objects that contain information about the location include the following properties:

Property Type Description

loc

Source Info Object

The location of the symbol in the source code.

When the symbol kind is namespace, the symbol object has the following additional properties:

Property Type Description

interface

Tranche Object

The interface of the namespace.

usingDirectives

Symbol Object[]

The using directives of the namespace.

When the symbol kind is record (e.g., class, struct, union), the symbol object has the following additional properties:

Property Type Description

tag

string

The type of record (e.g., class, struct, union).

defaultAccess

string

The default access level of the record members (e.g., public, private).

isTypedef

bool

Whether the record is a typedef.

bases

Base Info Object[]

The base classes of the record.

interface

Interface Object

The interface of the record.

template

Template Info Object

The template information of the record.

When the symbol kind is enum, the symbol object has the following additional properties:

Property Type Description

type

Type Info Object

The type information of the enum.

isScoped

bool

Whether the enum is scoped.

When the symbol kind is function, the symbol object has the following additional properties:

Property Type Description

isVariadic

bool

Whether the function is variadic.

isVirtual

bool

Whether the function is virtual.

isVirtualAsWritten

bool

Whether the function is virtual as written.

isPure

bool

Whether the function is pure.

isDefaulted

bool

Whether the function is defaulted.

isExplicitlyDefaulted

bool

Whether the function is explicitly defaulted.

isDeleted

bool

Whether the function is deleted.

isDeletedAsWritten

bool

Whether the function is deleted as written.

isNoReturn

bool

Whether the function is noreturn.

hasOverrideAttr

bool

Whether the function has the override attribute.

hasTrailingReturn

bool

Whether the function has a trailing return type.

isConst

bool

Whether the function is const.

isVolatile

bool

Whether the function is volatile.

isFinal

bool

Whether the function is final.

isNodiscard

bool

Whether the function is nodiscard.

isExplicitObjectMemberFunction

bool

Whether the function is an explicit object member function.

constexprKind

string

The constexpr kind of the function (e.g., consteval, constexpr).

storageClass

string

The storage class of the function (e.g., static, extern).

refQualifier

string

The reference qualifier of the function (e.g., &, &&).

class

string

The function class (e.g., constructor, conversion, destructor).

params

Param Object[]

The parameters of the function.

return

Type Info Object

The return type of the function.

template

Template Info Object

The template information of the function.

overloadedOperator

string

The overloaded operator of the function.

exceptionSpec

string

The exception specification of the function.

explicitSpec

string

The explicit specification of the function.

requires

string

The requires expression of the function.

When the symbol kind is typedef, the symbol object has the following additional properties:

Property Type Description

type

Type Info Object

The type information of the typedef.

template

Template Info Object

The template information of the typedef.

isUsing

bool

Whether the typedef is a using declaration.

When the symbol kind is variable, the symbol object has the following additional properties:

Property Type Description

type

Type Info Object

The type information of the variable.

template

Template Info Object

The template information of the variable.

constexprKind

string

The constexpr kind of the variable (e.g., consteval, constexpr).

storageClass

string

The storage class of the variable (e.g., static, extern).

isConstinit

bool

Whether the variable is constinit.

isThreadLocal

bool

Whether the variable is thread-local.

initializer

string

The initializer of the variable.

When the symbol kind is field (i.e. non-static data members), the symbol object has the following additional properties:

Property Type Description

type

Type Info Object

The type information of the field.

default

string

The default value of the field.

isMaybeUnused

bool

Whether the field is maybe unused.

isDeprecated

bool

Whether the field is deprecated.

isVariant

bool

Whether the field is a variant.

isMutable

bool

Whether the field is mutable.

isBitfield

bool

Whether the field is a bitfield.

hasNoUniqueAddress

string

Whether the field has the attribute.

bitfieldWidth

string

The width of the bitfield.

When the symbol kind is friend, the symbol object has the following additional properties:

Property Type Description

name

string

The name of the friend symbol or type.

symbol

Symbol Object

The friend symbol.

type

Type Info Object

The friend type.

When the symbol kind is alias, the symbol object has the following additional properties:

Property Type Description

aliasedSymbol

Name Info Object

The aliased symbol.

When the symbol kind is using, the symbol object has the following additional properties:

Property Type Description

class

string

The class of the using declaration (e.g., normal, typename, enum).

shadows

Symbol Object[]

The symbols being used.

qualifier

Name Info Object

The qualifier of the using declaration.

When the symbol kind is enumerator, the symbol object has the following additional properties:

Property Type Description

initializer

string

The initializer of the enumerator.

When the symbol kind is guide, the symbol object has the following additional properties:

Property Type Description

params

Param Object[]

The parameters of the guide.

deduced

Type Info Object

The deduced type of the guide.

template

Template Info Object

The template information of the guide.

explicitSpec

string

The explicit specification of the guide.

When the symbol kind is concept, the symbol object has the following additional properties:

Property Type Description

template

Template Info Object

The template information of the concept.

constraint

string

The constraint of the concept.

Source Info Fields

The Source Info object represents the location of the symbol in the source code. The source info object has the following properties:

Property Type Description

def

Location Object

Location where the entity was defined.

decl

Location Object[]

Locations where the entity was declared.

Tranche Object Fields

The Tranche object represents the symbols in a scope (e.g., namespace). The tranche object has the following properties:

Property Type Description

(symbol kind in plural form: e.g., classes, functions, variables)

Symbol Object[]

The symbols of that kind in the scope.

types

Symbol Object[]

The types in the scope.

staticfuncs

Symbol Object[]

The static functions in the scope.

overloads

Symbol Object[]

The overloads in the scope.

staticoverloads

Symbol Object[]

The static overloads in the scope.

Interface Object Fields

The Interface object represents the interface of a record (e.g., class, struct, union). The interface object has the following properties:

Property Type Description

public

Tranche Object

The public interface of the record.

protected

Tranche Object

The protected interface of the record.

private

Tranche Object

The private interface of the record.

Base Info Fields

The Base Info object represents a base class of a record. The base info object has the following properties:

Property Type Description

access

string

The access level of the base class.

isVirtual

bool

Whether the base class is virtual.

type

Type Info Object

The type information of the base class.

Template Info Fields

The Template Info object represents the template information of a record, function, or typedef. The template info object has the following properties:

Property Type Description

kind

string

The kind of template (e.g., explicit, partial).

primary

Symbol Object

The primary template.

params

tParam Object[]

The template parameters.

args

Type Info Object[]

The template arguments.

requires

string

The requires expression of the template.

Type Info Fields

The Type Info object represents the type information of a symbol. The type info object has the following properties:

Property Type Description

kind

string

The kind of type (e.g., named, decltype, auto, pointer, reference, array, function).

is-pack

bool

Whether the type is a pack expansion.

name

string

The name of the type.

operand

string

The operand of the type.

keyword

string

The keyword of the type.

constraint

string

The constraint of the type.

cv-qualifiers

string

The cv qualifier of the type (e.g., const, volatile).

parent-type

Type Info Object

The parent type of the type.

pointee-type

Type Info Object

The pointee type of the type.

element-type

Type Info Object

The element type of the type.

bounds-value

string

The bounds value of the type.

bounds-expr

string

The bounds expression of the type.

return-type

Type Info Object

The return type of the type.

param-types

Type Info Object[]

The parameter types of the type.

exception-spec

string

The exception specification of the type.

ref-qualifier

string

The reference qualifier of the type.

is-variadic

bool

Whether the type is variadic.

Param Fields

The Param object represents the parameter of a function. The param object has the following properties:

Property Type Description

name

string

The name of the parameter.

type

Type Info Object

The type information of the parameter.

default

string

The default value of the parameter.

Name Info Fields

The Name Info object represents the name of a symbol. The name info object has the following properties:

Property Type Description

name

string

The name of the symbol.

symbol

string

The unique identifier of the symbol.

args

Type Info Object[]

The template arguments of the symbol.

prefix

string

The prefix of the symbol.

Location Fields

The Location object represents the location of a symbol in the source code. The location object has the following properties:

Property Type Description

path

string

The path of the source file.

file

string

The filename of the source file.

line

integer

The line number of the symbol.

kind

string

The kind of file (e.g., source, system, other).

documented

bool

Whether the symbol is documented.

TParam Fields

The TParam object represents a template parameter of a record, function, or typedef. The tparam object has the following properties:

Property Type Description

kind

string

The kind of template parameter (e.g., type, non-type, template).

name

string

The name of the template parameter.

is-pack

bool

Whether the template parameter is a pack expansion.

default

string

The default value of the template parameter.

key

string

The key kind of the template parameter.

constraint

string

The constraint of the template parameter.

type

Type Info Object

The type information of the template parameter.

params

TParam Object[]

The template parameters of the template parameter.

Targ Fields

The Targ object represents a template argument of a record, function, or typedef. The targ object has the following properties:

Property Type Description

kind

string

The kind of template argument (e.g., type, non-type, template).

is-pack

bool

Whether the template argument is a pack expansion.

type

Type Info Object

The type information of the template argument.

value

string

The value of the template argument.

name

string

The name of the template argument.

template

Template Info Object

The template information of the template argument.

Config Fields

The Config object represents the configuration object. It includes all values provided to MrDocs in the configuration file or via the command line. Please refer to the configuration file reference for more information.

Edit this Page