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()