Types of Comments

According to CMinx, the content of a CMake file can be broken into three categories:

  1. Documentation comments - what CMinx extracts

  2. Annotation comments - Comments, but should not be extracted by CMinx

  3. CMake source code - Everything else

To distinguish between the documentation and annotation comments CMinx borrows the convention that documentation comments start with an additional comment character. Thus to indicate that a CMake comment is documentation use #[[[ (the block comment should still end with #]]). For example:

#[[[
# This function has very basic documentation.
#
# This function's description stays close to idealized formatting and does not do
# anything fancy.
#
# :param person: The person this function says hi to
# :param me: What my name is
# :type person: string
# :type me: string
#]]
function(say_hi_to person me)
    message("Hi ${person}, I am ${me}")
endfunction()

For comparison, an annotation comment looks like:

#[[
# This is a normal block comment and will not
# be treated as a doccomment.
#]]
include_guard()

Sometimes documentation comments need additional information in their headers to inform CMinx about the type of documentation the comment represents. This information is contained in the first line of the documentation comment (the line with #[[[) and is marked by a special directive start character @. For example, a module documentation comment contains the @module directive:

#[[[ @module
# This is a basic CMake module.
# The :code:`@module` component is required and
# must appear on the first line. An
# optional module name may appear after the
# module tag, if it is not present the module
# name is autogenerated as usual. This
# file allows the module name to be autogenerated.
#]]

Note

Doccomment directives marked by @ are different from RST directives. They are hints to CMinx for how to parse the doccomment and how to format it in the output, they are not passed through to the generated RST and therefore Sphinx is entirely unaware of them. Consider them akin to preprocessor directives.