3 General usage

Documentation top file must be present in the documentation directory (default is ./doc) in a file named top.mkdoc.

An additional mkdoc.conf file contains @setopt tag to define configuration options.

To create a directory containing initial documentation files, use the bootstrap option as explained in the Quick start section.

All generated documentation files will be created in a sub-directory named after the output format in use (doc/html/, doc/latex/, ...).

Some options exist to change configuration file name and default search path.

MkDoc overall process works this way:

• It reads configuration from command line and configuration file.

• It parses plain documentation from the top.mkdoc file into an DOM tree and optionally parse declarations from header files when the @parse tag is encountered.

• It parses more header files specified on the command line, if any.

• It inserts code documentation in the DOM tree as requested using the @insert tag.

• It resolves all section and code symbol cross references.

• It finally writes the documentation file(s) from the abstract DOM tree using the output format drivers.

MkDoc parses C and C++ header files passed on command line or specified with the @parse tag from plain documentation.

Each parsed file adds to a single, project global, declarations syntax tree. Declarations from parsed files must not be conflicting; this means that all files must be able to get included in the same C or C++ source file in any order without symbol name conflicts.

Preprocessor macros expansion is performed the usual way and all conditional branches are explored, read the Preprocessor section for details.

Header files are parsed in specified order. However if a header file to be processed is included earlier by an other file, it is processed when it is first encountered instead, read the @parse tag section for details.

Included files that are not specified by the user are still parsed for preprocessor macro to expand but declarations will not appear in the documentation. If they can't be found in include paths, they are silently ignored.

MkDoc has to deal with many different kind of symbols: declared C/C++ identifiers, macro, header files, modules; it sometimes faces situations where multiple declarations exist with the same identifier.

Symbols of different types actually reside in different name-spaces because a macro can have the same name as a variable or header file for instance.

When using identifier in the documentation, a prefix must be provided to specify the type of symbol the identifier refers to. Here are the rules:

• An unqualified or qualified C/C++ identifier needs no prefix.

• An @alias tag name must be surrounded by double underscore characters (__name__ ).

• A preprocessor macro name must be prefixed by "#".

• A header file name must be prefixed by "@".

• A module name must be prefixed by "+". Some module names may contain spaces and require use of the bracketed syntax.

• All symbols can be referred to using a non ambiguous numeric id which is only valid during a single execution of MkDoc. The numeric id prefix is "!". Numeric ids are generated by @foreach tag and @lookup tag.

If your code use classes and types from other libraries, you may want to tell MkDoc about it. Reference files for external libraries can be passed along with header files so that generated documentation contains references to external symbols. MkDoc is able to parse mkdoclib files and doxygen tag files.

Some mkdoclib files are provided in the distribution extra/ directory for standard C++ library and Qt library. You may use them with the @parse tag or on the command line, without specifying full path name:

Http urls to online mkdoclib files may be used too:

MkDoc is able to generate mkdoclib files along with the documentation for later use in other projects:

See also mkdoclib_create and mkdoclib_url.