Bracket Comments are not seen as valid comments for functions

[RonaldHiemstra]

Bracket Comment, also known as block comments (comments between #[[ and ]]) can not be used to comment functions.

When using bracket comments, cmake-lint returns the following error:

C:\...\CMakeLists.txt:22,00: [C0112] Empty docstring on function or macro declaration

cmake code:

#[[
Some dummy function, doing nothing.
]]
function(dummy)

endfunction()

[cheshirekow]

That's correct. Bracket comments are treated as literal and not considered as doc comments.

[murzz]

Is this a hard design decision?

[RonaldHiemstra]

If I use normal comments, cmake-format re-formats my comments. @cheshirekow How can I properly document a function?

[cheshirekow]

@murzz I wouldn't say it's a hard design decision, but it was an intentional one. It ensures that there is an easy way to get verbatim comments into the document.

@RonaldHiemstra

If I use normal comments, cmake-format re-formats my comments.

Well... that's kind of the point. Can you maybe provide an example where the behavior is not ideal?

[RonaldHiemstra]

I use doxygen style comment wherever possible, so a function documentation would look like the following example:

# @brief Do foo.
# @param[in] FOO_ARG some example argument.
# @param[in] FOO_ARG_LIST some example argument containing a list of values.
# @note In order to allow correct functioning, the function requires the following global variables to be set:
#   - CMAKE_BINARY_DIR: Directory where the generated binaries will be stored.
#   - CMAKE_SOURCE_DIR: Directory where the source of the Cmake project is stored.
# The following global variables are used as well (Setting is optional)
#   - GIT_BRANCH: Git branch for which the build is done
#   - GIT_COMMIT: Git commit for which the build is done
#   - BUILD_ID: Build number of Jenkins
function(foo)
  set(options)
  set(oneValueArgs FOO_ARG)
  set(multiValueArgs FOO_ARG_LIST)
  cmake_parse_arguments(FOO_ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}")
  # foo implementation ...
endfunction()