docs: add docstrings for functions

Author: aminya

src/Conan.cmake

@@ -1,3 +1,4 @@
+# Run Conan for dependency management
 macro(run_conan)
   # Download automatically, you can also just copy the conan.cmake file
   if(NOT EXISTS "${CMAKE_BINARY_DIR}/conan.cmake")

src/DynamicProjectOptions.cmake

@@ -4,21 +4,21 @@
 #  * ENABLE_CLANG_TIDY: ON for Ninja/Makefiles
 #  * ENABLE_SANITIZER_UNDEFINED: ON for Compilers that support it
 #  * ENABLE_CPPCHECK: ON for Ninja/Makefiles
-
+#
 # For non-developer builds
 #  -DENABLE_DEVELOPER_MODE:BOOL=OFF
 # Is recommended
-
+#
 # In developer mode, all features have options that show up in the CMake GUI tools
-
+#
 # dynamic_project_options() macro enables all recommended defaults with appropriately
 # applied options from the GUI which are set
-
+#
 # Any default can be overridden
 # set(<feature_name>_DEFAULT <value>) - set default for both user and developer modes
 # set(<feature_name>_DEVELOPER_DEFAULT <value>) - set default for developer mode
 # set(<feature_name>_USER_DEFAULT <value>) - set default for user mode
-
+#
 macro(dynamic_project_options)
   option(ENABLE_DEVELOPER_MODE "Set up defaults for a developer of the project, and let developer change options" OFF)
   if(NOT ${ENABLE_DEVELOPER_MODE})

src/Linker.cmake

@@ -1,3 +1,6 @@
+# TODO use function arguments instead of CMake cache variables and options
+
+# Set the linker to use for the linking phase
 macro(configure_linker project_name)
   include(CheckCXXCompilerFlag)
 

src/PackageProject.cmake

@@ -1,5 +1,7 @@
 # Uses ycm (permissive BSD-3-Clause license) and ForwardArguments (permissive MIT license)
 
+# A function that packages the project for external usage (e.g. from vcpkg, Conan, etc).
+# See the [README.md] for more details
 function(package_project)
   cmake_policy(SET CMP0103 NEW) # disallow multiple calls with the same NAME
 

src/Standards.cmake

@@ -1,3 +1,4 @@
+# Set the default copmiler standards if not specified
 macro(set_standards)
 
   # if the default CMAKE_CXX_STANDARD is not set, detect the latest CXX standard supported by the compiler and use it.

src/StaticAnalyzers.cmake

@@ -1,3 +1,4 @@
+# Enable static analysis with Cppcheck
 macro(enable_cppcheck CPPCHECK_OPTIONS)
   find_program(CPPCHECK cppcheck)
   if(CPPCHECK)
@@ -52,6 +53,7 @@ macro(enable_cppcheck CPPCHECK_OPTIONS)
   endif()
 endmacro()
 
+# Enable static analysis with clang-tidy
 macro(enable_clang_tidy)
   find_program(CLANGTIDY clang-tidy)
   if(CLANGTIDY)
@@ -115,6 +117,7 @@ macro(enable_clang_tidy)
   endif()
 endmacro()
 
+# Enable static analysis with include-what-you-use
 macro(enable_include_what_you_use)
   find_program(INCLUDE_WHAT_YOU_USE include-what-you-use)
   if(INCLUDE_WHAT_YOU_USE)

src/Tests.cmake

@@ -1,3 +1,4 @@
+# Enable coverage reporting for gcc/clang
 function(enable_coverage project_name)
   if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
     target_compile_options(${project_name} INTERFACE --coverage -O0 -g)

src/Utilities.cmake

@@ -83,6 +83,7 @@ function(set_env_from_string env_string)
   endforeach()
 endfunction()
 
+# Get all the CMake targets
 function(get_all_targets var)
   set(targets)
   get_all_targets_recursive(targets ${CMAKE_CURRENT_SOURCE_DIR})
@@ -91,6 +92,7 @@ function(get_all_targets var)
       PARENT_SCOPE)
 endfunction()
 
+# Get all the installable CMake targets
 function(get_all_installable_targets var)
   set(targets)
   get_all_targets(targets)
@@ -108,6 +110,7 @@ function(get_all_installable_targets var)
       PARENT_SCOPE)
 endfunction()
 
+# Get all the CMake targets in the given directory
 macro(get_all_targets_recursive targets dir)
   get_property(
     subdirectories
@@ -124,6 +127,7 @@ macro(get_all_targets_recursive targets dir)
   list(APPEND ${targets} ${current_targets})
 endmacro()
 
+# Is CMake verbose?
 function(is_verbose var)
   if("CMAKE_MESSAGE_LOG_LEVEL" STREQUAL "VERBOSE"
      OR "CMAKE_MESSAGE_LOG_LEVEL" STREQUAL "DEBUG"

src/Vcpkg.cmake

@@ -1,5 +1,6 @@
 include(FetchContent)
 
+# Install vcpkg and vcpkg dependencies: - should be called before defining project()
 macro(run_vcpkg)
   # named boolean ENABLE_VCPKG_UPDATE argument
   set(options ENABLE_VCPKG_UPDATE)