Excluding Code from Documentation
A line starting with the @no-doc directive in a doccomment excludes
the documented command from the generated documentation. When the command
starts a block, such as function(), macro() or
cpp_class(), the whole block is excluded, including any documented
commands inside it. This also applies when undocumented commands are
included through the include_undocumented_* settings.
#[[[
# This function is documented.
#]]
function(documented_function)
endfunction()
#[[[
# @no-doc
#
# This function is an implementation detail, so it is not documented,
# along with any documented commands inside it.
#]]
function(_internal_function)
#[[[
# Not documented either.
#]]
set(internal_variable "")
endfunction()
#[[[
# @no-doc
#]]
option(INTERNAL_OPTION "Not documented" OFF)
#[[[
# Documentation resumes after the command or block.
#]]
set(documented_variable "")
For commands implemented by the function() or macro() that
follows them, such as ct_add_test(), ct_add_section(),
cpp_member() and cpp_constructor(), the following definition
is excluded as well.
To exclude a whole file, put @no-doc in the first doccomment of the
file without attaching it to a command, or in the module doccomment. No page
is generated for the file, and it is left out of its directory’s
index.rst. A @no-doc doccomment anywhere else that is not
attached to a command is an error.
Note
Blank lines do not separate a doccomment from the command after it. If the
first doccomment of the file is followed by a command, even after blank
lines, @no-doc excludes only that command rather than the file.
To reliably exclude a whole file, put @no-doc in a module
doccomment at the top of the file:
#[[[ @module
# @no-doc
#]]
include_guard()