Introduction

MkDoc is a code project documentation tool. It is inspired from the kdoc project with complete rewrite.

MkDoc has been designed to parse C and complex C++ code while still producing clear documentation for developers and library users.

Unlike most code generation tools Mkdoc does not simply write generated code documentation with piece of user text inside. Instead it handles plain documentation files with sections and other constructs (like texinfo or latex) and inserts piece of generated code documentation on request. This way it does not enforce the way you structure your document. Template documentation source files are provided when starting a new project so that MkDoc generates automatic code documentation in usual way.

You can have a look to the Sample projects section to see examples of generated documents.

Documentation generation features are:

• Parse both code and plain documentation files and generate cross references as requested.

• Document top node is a plain documentation file and code documentation is inserted on request with fine control of what gets inserted. Code documentation sections layout is described in editable template files using the same language as plain documentation.

• Proper use of configuration options and conditional documentation tags allow generation of both end user library manual and internals doc from the same plain documentation source, with fine control on what is displayed and hidden.

• Code declarations are pretty-printed from the internal abstract syntax tree, giving uniform documentation and configurable C++ qualified naming convention.

• Declarations, namespaces and files can be grouped inside modules. Modules can be nested.

• MkDoc internally builds a documentation DOM tree and relies on one or more drivers to write the output document(s). Available output formats are: xhtml, GNU Texinfo, LaTeX, DocBook, Plain text, Man page, RTF and reStructuredText. More can be implemented quite easily.

C++ parser features are:

• It is able to parse C and C++ code with documentation tags in code comments like javadoc or Doxygen

• It has been designed to parse advanced C++ constructs to enable exposing a simple library API to the user while hiding complex internal code design patterns.

• It is able to parse class inheritance, template specialization and do template instantiation.

• It is able to handle complex cases like inheritance from template parameters and still find inherited functions and write nice documentation of exposed class showing public inherited members of hidden internal classes.

• C++ name lookup rules are followed strictly, no bad documentation references links are inserted even if multiple symbols with the same names exists in different scopes.

C preprocessor features are:

• The embedded preprocessor enables MkDoc to expose declarations which take place in macro expansion with information about involved header files, macros and line positions.

• The preprocessor keeps track of nested conditional context as well. The resulting conditional expression required for a declaration to actually take place can be exposed in the documentation.

• MkDoc can be configured to accept multiple declarations of the same macro or symbol name and include links to homonym declarations, useful for repeated declaration with different preprocessor conditions.

• Links to online source code repository with file and line number can be automatically generated for all declarations.