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.

Additionally, the /*+ doc */ form of comment allows appending more paragraphs to a previous comment, before the declaration. This is useful when parts of the doc content is expanded from a C macro.

Documentation comments can be used in C macros to document expanded declarations. To achieve this, Mkdoc stores comments in macros content. Because of this, you can not put a documentation comment for the macro itself at the end of the macro line.

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, @csee, @debug, @deprecated, @else, @end, @error, @experimental, @file, @foreach, @header, @hidden, @hidecontent, @ifeq, @ifneq, @ifnopt, @ifnsymtype, @ifopt, @ifsymattr, @ifsymtype, @index, @info, @internal, @internalmembers, @label, @lookup, @main, @mgroup, @mgrouporder, @module, @multiple, @noexpand, @order, @override, @prototype, @scope, @see, @setopt, @short, @showcontent, @showvalue, @visible, @warning, @xcsee and @xsee.

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

Valid XHTML 1.0 StrictGenerated by diaxen on Sat Apr 30 17:58:47 2016 using MkDoc