5 Documentation format

Documentation content may appears in plain documentation files (.mkdoc) and in code comments in header files.

Documentation content is composed of text and documentation tags. Some tags are documentation formatting tags and other tags are related to code declarations. Code related tags may only be used in code comments to document a declaration.

Paragraph boundaries occur when line is left blank between two pieces of text.

Documentation tags first character is @. This character must be escaped in normal text using a double @.

Some tags except one or more arguments. Arguments which may contain spaces must be enclosed between { and } characters. Tags can not appear in tag arguments. Brace character { may be escaped in normal text to avoid interpretation of { as start of an optional tag argument in some case.

There are two ways to write documentation comments in code header:

  • Before the described declaration: /** doc text and tags here */

  • After the described declaration: //< doc text and tags here

Some tags can not be used with the latter form.

Documentation comments can be used in C macros to document expanded declarations. To achieve this, Mkdoc stores comments in macros content; This prevent use of //< C++ style comments to document macros.

There are different categories of documentation tags. Some are plain documentation tags and other are specific code documentation tags. Some miscellaneous tags are presented in the Miscellaneous tags section.

Inline and transparent tags  

Transparent tags don't directly take part in writing document content. The following tags which are mainly used to specify code attributes or information are transparent: @alias, @brief, @c, @debug, @deprecated, @else, @end, @error, @experimental, @file, @foreach, @header, @hidden, @hidecontent, @ifeq, @ifneq, @ifnopt, @ifnsymtype, @ifopt, @ifsymattr, @ifsymtype, @index, @info, @internal, @label, @lookup, @main, @mgroup, @mgrouporder, @module, @multiple, @noexpand, @order, @override, @prototype, @scope, @see, @setopt, @short, @showcontent, @showvalue, @visible, @warning and @xsee.

Inline tags are used to write content but do not automatically end the current paragraph. Inline tags are: @b, @e, @em, @group, @include, @insert, @invoke, @iraw, @math, @p, @rcs, @ref, @sourcelink, @sourceref, @strong, @this, @tt, @url and @xref. Transparent tags do not end the current paragraph either.

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