Types of Comments
According to CMinx, the content of a CMake file can be broken into three categories:
Documentation comments - what CMinx extracts
Annotation comments - Comments, but should not be extracted by CMinx
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 marked by a special directive start
character @ at the start of a line. For example, a module
documentation comment contains the @module directive, which must be
on the first line of the documentation comment (the line with #[[[):
#[[[ @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.
A line starting with @ that is not a CMinx directive is kept as text,
and CMinx logs a warning so that misspelled directives are noticed. To keep
such a line without the warning, escape it as \@, which is written
to the generated RST as @.