Adding contracts for CMake functions.

Author: sean-parent

cmake/cpp-library-ci.cmake

@@ -4,8 +4,9 @@
 #
 # This module handles GitHub Actions workflow generation with PROJECT_NAME substitution
 
-# Function to configure CI workflow template
-# Arguments: force_init (boolean) - whether to overwrite existing file
+# Generates GitHub Actions CI workflow from template with PROJECT_NAME substitution.
+# - Postcondition: .github/workflows/ci.yml created from template if not present
+# - With force_init: overwrites existing workflow file
 function(_cpp_library_setup_ci force_init)
     set(ci_template "${CPP_LIBRARY_ROOT}/templates/.github/workflows/ci.yml.in")
     set(ci_dest "${CMAKE_CURRENT_SOURCE_DIR}/.github/workflows/ci.yml")

cmake/cpp-library-docs.cmake

@@ -2,6 +2,9 @@
 #
 # cpp-library-docs.cmake - Documentation setup with Doxygen
 
+# Creates 'docs' target for generating API documentation with Doxygen and doxygen-awesome-css theme.
+# - Precondition: NAME, VERSION, and DESCRIPTION specified; Doxygen available
+# - Postcondition: 'docs' custom target created, Doxyfile configured, theme downloaded via CPM
 function(_cpp_library_setup_docs)
     set(oneValueArgs
         NAME

cmake/cpp-library-install.cmake

@@ -12,8 +12,10 @@
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
-# Function to setup installation for a library target
-# This should be called from _cpp_library_setup_core when PROJECT_IS_TOP_LEVEL
+# Configures CMake install rules for library target and package config files.
+# - Precondition: NAME, VERSION, and NAMESPACE specified; target NAME exists
+# - Postcondition: install rules created for target, config files, and export with NAMESPACE:: prefix
+# - Supports header-only (INTERFACE) and compiled libraries, uses SameMajorVersion compatibility
 function(_cpp_library_setup_install)
     set(oneValueArgs
         NAME        # Target name (e.g., "stlab-enum-ops")

cmake/cpp-library-setup.cmake

@@ -2,7 +2,8 @@
 #
 # cpp-library-setup.cmake - Core library setup functionality
 
-# Function to get version from git tags
+# Returns version string from latest git tag, falling back to "0.0.0".
+# - Postcondition: OUTPUT_VAR set to version string with 'v' prefix removed
 function(_cpp_library_get_git_version OUTPUT_VAR)
     # Try to get version from git tags
     execute_process(
@@ -24,6 +25,9 @@ function(_cpp_library_get_git_version OUTPUT_VAR)
     endif()
 endfunction()
 
+# Creates library target (INTERFACE or compiled) with headers and proper configuration.
+# - Precondition: NAME, NAMESPACE, and REQUIRES_CPP_VERSION specified
+# - Postcondition: library target created with alias NAMESPACE::CLEAN_NAME, install configured if TOP_LEVEL
 function(_cpp_library_setup_core)
     set(oneValueArgs
         NAME
@@ -100,7 +104,9 @@ function(_cpp_library_setup_core)
 
 endfunction()
 
-# Function to copy static template files
+# Copies template files (.clang-format, .gitignore, etc.) to project root if not present.
+# - Postcondition: missing template files copied to project, CI workflow configured with PROJECT_NAME substitution
+# - With FORCE_INIT: overwrites existing files
 function(_cpp_library_copy_templates)
     set(options FORCE_INIT)
     cmake_parse_arguments(ARG "${options}" "" "" ${ARGN})

cmake/cpp-library-testing.cmake

@@ -6,7 +6,8 @@
 # This file is kept for backward compatibility but the actual implementation
 # is now in the _cpp_library_setup_executables function.
 
-# Legacy function - now delegates to the consolidated implementation
+# Delegates to _cpp_library_setup_executables for backward compatibility.
+# - Postcondition: test executables configured via _cpp_library_setup_executables
 function(_cpp_library_setup_testing)
     set(oneValueArgs
         NAME

cpp-library.cmake

@@ -18,7 +18,10 @@ include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-docs.cmake")
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-install.cmake")
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-ci.cmake")
 
-# Shared function to handle examples and tests consistently
+# Creates test or example executables and registers them with CTest.
+# - Precondition: doctest target available via CPM, source files exist in TYPE directory
+# - Postcondition: executables created and added as tests (unless in clang-tidy mode)
+# - Executables with "_fail" suffix are added as negative compilation tests
 function(_cpp_library_setup_executables)
     set(oneValueArgs
         NAME
@@ -99,7 +102,10 @@ function(_cpp_library_setup_executables)
 
 endfunction()
 
-# Main entry point function - users call this to set up their library
+# Sets up a C++ header-only or compiled library with testing, docs, and install support.
+# - Precondition: PROJECT_NAME defined via project(), at least one HEADERS specified
+# - Postcondition: library target created, version set from git tags, optional tests/docs/examples configured
+# - When PROJECT_IS_TOP_LEVEL: also configures templates, testing, docs, and installation
 function(cpp_library_setup)
     # Parse arguments
     set(oneValueArgs