cmake added/revisited all Synopsis

Function descriptions for functions which call cmake_parse_arguments().

cmake/CommonModules/TinyCommon.cmake

@@ -2,9 +2,22 @@ include_guard(GLOBAL)
 
 include(CheckCXXCompilerFlag)
 
+# Common interface library used by all TinyORM targets
+#
 # Set common variables and create interface-only library target so all other targets
 # will be able to link to, either directly or transitively, to consume common compile
-# options/definitions
+# options/definitions.
+#
+# Synopsis:
+# tiny_common(<target>
+#   NAMESPACE <namespace>
+#   [EXPORT] NAME <name>
+# )
+#
+# <target> name to operate on.
+# NAMESPACE name used for an Alias Target.
+# EXPORT set the EXPORT_NAME target property to <name>.
+# NAME used for an Alias Target name and EXPORT_NAME target property.
 function(tiny_common target)
 
     # Arguments

cmake/CommonModules/TinyFeatureOptions.cmake

@@ -145,27 +145,38 @@ depends on condition: ${depends})")
 
 endmacro()
 
-# Add a simple build option which controls compile definition(s) for a target.
+# Add the boolean build option and compile definition/s for a target in one shot.
+#
+# Call the option() command if an option <name> is not defined yet and initialize its
+# default value from the <environment-variable-name> if given, otherwise
+# from the <default-value>. Call the target_compile_definitions(<scope>)
+# with the <enabled-compile-definitions> if an option is enabled (ON), otherwise use
+# the <disabled-compile-definitions>. Call the add_feature_info() and mark_as_advanced()
+# functions if FEATURE or ADVANCED is given.
 #
 # Synopsis:
 # target_optional_compile_definitions(<target> <scope> [ADVANCED] [FEATURE]
-#   NAME <name> DESCRIPTION <description> DEFAULT <default_value>
-#   DEFAULT_FROM_ENVIRONMENT <environment_variable_name>
-#   [ENABLED [enabled_compile_definitions...]]
-#   [DISABLED [disabled_compile_definitions...]]
+#   NAME <name> DESCRIPTION <description> DEFAULT <default-value>
+#   [DEFAULT_FROM_ENVIRONMENT <environment-variable-name>]
+#   [ENABLED [<enabled-compile-definitions>...]]
+#   [DISABLED [<disabled-compile-definitions>...]]
 # )
 #
-# NAME, DESCRIPTION and DEFAULT are passed to option() command.
-# If FEATURE is given, they are also passed to add_feature_info() command.
-# ADVANCED calls the mark_as_advanced(<NAME>) command.
-# <scope> determines the scope for the following compile definitions.
-# ENABLED lists compile definitions that will be set on <target> when option is enabled.
-# DISABLED lists compile definitions that will be set on <target> when option is disabled.
+# <target> name to operate on.
+# <scope> for the target_compile_definitions() command.
+# NAME of a variable to process, it's directly passed to the option() and
+# add_feature_info() commands.
+# DESCRIPTION for the option() and add_feature_info() commands.
+# DEFAULT initial value for the option() command, used if the <environment-variable-name>
+# is not empty or undefined.
+# ADVANCED call the mark_as_advanced(<name>) command.
+# FEATURE pass the <name> and <description> values also to the add_feature_info() command.
+# ENABLED <enabled-compile-definitions> to set on the <target> when option is enabled.
+# DISABLED <disabled-compile-definitions> to set on the <target> when option is disabled.
 # ENABLED or DISABLE are passed to the target_compile_definitions() command.
 # DEFAULT_FROM_ENVIRONMENT get a default value for the option() command from the given
-# environment variable if it's defined otherwise use a value from the given <DEFAULT>
-# argument.
-# DEFAULT and DEFAULT_FROM_ENVIRONMENT can't be if they are passed and they must be
+# <environment-variable-name> if defined, otherwise use the <default-value>.
+# DEFAULT and DEFAULT_FROM_ENVIRONMENT can't be empty if they are passed and they must be
 # of the boolean type.
 function(target_optional_compile_definitions target scope)
 

cmake/CommonModules/TinyHelpers.cmake

@@ -166,8 +166,23 @@ function(tiny_create_buildtree_tagfiles filepaths)
 
 endfunction()
 
-# Find version numbers in the version header file, search following tokens
-# <PREFIX>_VERSION_<MAJOR,MINOR,BUGFIX,BUILD>
+# Find version numbers in the version header file using the given <prefix>
+#
+# Search following tokens <prefix>_VERSION_<MAJOR|MINOR|BUGFIX|BUILD> and return obtained
+# values using the <out_xyz> variables.
+#
+# Synopsis:
+# tiny_read_version(out_version out_major out_minor out_patch out_tweak
+#   VERSION_HEADER <filepath>
+#   PREFIX <prefix>
+#   HEADER_FOR <project-name>
+# )
+#
+# <out_version> output variable for the whole version number.
+# <out_major|minor|patch|tweak> output variables for individual version numbers.
+# VERSION_HEADER absolute filepath is directly passed to the file(STRINGS).
+# PREFIX for the file(STRINGS REGEX) to find #define <prefix>_VERSION_<MAJOR|...> lines.
+# HEADER_FOR project name used in the message(DEBUG) (use TinyXyz_ns variables for this).
 function(tiny_read_version out_version out_major out_minor out_patch out_tweak)
 
     # Arguments
@@ -180,9 +195,11 @@ function(tiny_read_version out_version out_major out_minor out_patch out_tweak)
 ${TINY_UNPARSED_ARGUMENTS}")
     endif()
 
-    if("${TINY_VERSION_HEADER}" STREQUAL "" OR "${TINY_HEADER_FOR}" STREQUAL "")
+    if("${TINY_VERSION_HEADER}" STREQUAL "" OR "${TINY_PREFIX}" STREQUAL "" OR
+            "${TINY_HEADER_FOR}" STREQUAL ""
+    )
         message(FATAL_ERROR "The ${CMAKE_CURRENT_FUNCTION}() is missing single-valued \
-keyword or its value is empty: HEADER_FOR, VERSION_HEADER")
+keyword or its value is empty: HEADER_FOR, PREFIX, VERSION_HEADER")
     endif()
 
     # Body
@@ -237,17 +254,22 @@ endfunction()
 
 # Command for manipulating CMAKE_RC_FLAGS, supports APPEND and RESTORE operations
 #
-# Append flags to the CMAKE_RC_FLAGS. It will also save and restore original content
+# Append flags to the CMAKE_RC_FLAGS. It will also save and restore the original content
 # of the CMAKE_RC_FLAGS variable, so that rc/windres compilation commands are not
-# polluted with include paths from previous calls.
+# polluted with include paths from previous tiny_rc_flags(APPEND) function calls.
 #
 # Synopsis:
 # tiny_rc_flags(APPEND [<flags>...])
 #
+# APPEND the given flags, it only restores the original CMAKE_RC_FLAGS value and
+# appends nothing if the <flags> value is empty.
+#
 # Restore the original value of CMAKE_RC_FLAGS.
 #
 # Synopsis:
 # tiny_rc_flags(RESTORE)
+#
+# RESTORE the original CMAKE_RC_FLAGS value.
 function(tiny_rc_flags)
 
     # Arguments
@@ -697,8 +719,22 @@ function(tiny_fix_ccache)
 
 endfunction()
 
-# Set the Compatible Interface Requirement for the project's major version using
-# the given target
+# Set the Compatible Interface Requirement for the given property names
+#
+# They are passed to the foreach() loop, set the INTERFACE_<name> <target> property value
+# that is obtained from the <target>'s property <name>, and then the <name> is appended
+# to the COMPATIBLE_INTERFACE_STRING <target> property.
+#
+# Every TinyORM library sets the Compatible Interface Requirement for the VERSION_MAJOR
+# and SOVERSION target properties.
+#
+# Synopsis:
+# tiny_set_compatible_interface_string(<target>
+#   PROPERTIES <name>...
+# )
+#
+# <target> name to operate on.
+# PROPERTIES names list for which to add the Compatible Interface Requirements.
 function(tiny_set_compatible_interface_string target)
 
     # Arguments

cmake/CommonModules/TinyResourceAndManifest.cmake

@@ -1,6 +1,24 @@
 include_guard(GLOBAL)
 
 # Configure Windows resource and manifest files
+#
+# Synopsis:
+# tiny_resource_and_manifest(<target> [TEST]
+#   [OUTPUT_DIR <dir>]
+#   [RESOURCES_DIR <dir>]
+#   [RESOURCE_BASENAME <resource-basename>]
+#   [MANIFEST_BASENAME <manifest-basename>]
+# )
+#
+# <target> name to operate on.
+# TEST to configure the test <target>, all tests use the same TinyTest.rc.in file.
+# OUTPUT_DIR relative folder path for the configure_file() for generated content.
+# RESOURCES_DIR relative or absolute folder path where the TinyXyz.rc.in file is located.
+# RESOURCE_BASENAME basename for the resource file, eg. TinyOrm will use TinyOrm.rc.in.
+# The <target> name and for TEST the TinyTest will be used if is empty or undefined.
+# MANIFEST_BASENAME basename for the manifest file, eg. TinyOrm library will use
+# TinyOrm.dll.manifest, for executables it will be eg. tom.exe.manifest.
+# The <resource-basename> will be used if empty or undefined.
 function(tiny_resource_and_manifest target)
 
     # Arguments

cmake/CommonModules/TinyToolchainRequirement.cmake

@@ -69,7 +69,24 @@ satisfied (also used by tiny_configure_test_pch()).")
 
 endfunction()
 
-# Make minimum toolchain version a requirement
+# Verify the minimum toolchain and Qt versions
+#
+# Make the minimum toolchain and Qt versions a requirement and throw the FATAL_ERROR if
+# this requirement is not satisfied (version is less than required). It checks compilers
+# and Qt framework versions. All <xyz-version> argument values are required.
+#
+# Synopsis:
+# tiny_toolchain_requirement(
+#   MSVC <msvc-version> GCC <gcc-version>
+#   CLANG <clang-version> CLANG_CL <clangcl-version>
+#   QT <qt-version>
+# )
+#
+# MSVC minimum <msvc-version> required.
+# GCC minimum <gcc-version> required.
+# CLANG minimum <clang-version> required.
+# CLANG_CL minimum <clangcl-version> required.
+# QT framework minimum <qt-version> required.
 function(tiny_toolchain_requirement)
 
     # Arguments

cmake/Modules/TinySources.cmake

@@ -849,38 +849,48 @@ endfunction()
 
 # Wrapper function for the target_sources() (for both overloads)
 #
-# Create header file sets (or add to the existing sets) or add header files and add
-# source files to the given target and call target_include_directories($<BUILD_INTERFACE>)
-# in one shot.
+# Create header file sets (or add to the existing sets) or add header and source files
+# to the given target and call target_include_directories($<BUILD_INTERFACE>) in one shot.
 #
 # Obtain public and private headers and source files, and create public/private
 # file set/s, or add files to an existing file set/s, and add source files
 # for the given target.
 #
+# Synopsis:
 # tiny_target_sources(<target>
-#   [FILE_SET] PREFIX <name> [BASE_DIRS <dirs>...]
+#   FILE_SET PREFIX <name>
+#   [BASE_DIRS [<dirs>...]]
 # )
 #
+# <target> name to operate on.
 # FILE_SET call the target_sources(FILE_SET) overload.
-# PREFIX prefix for FILE_SET argument value and for calling tinyxyz_sources()
-# function to obtain header and source files. Cannot be undefined or empty.
+# PREFIX for the FILE_SET argument value and for calling the tinyxyz_sources() function
+# to obtain header and source files. Cannot be empty or undefined.
 # BASE_DIRS these directories are directly passed to the target_sources(BASE_DIRS)
 # for public and private header files. The _private suffix is appended for every
-# directory path for private header files. It cannot end with slahes❗ Empty or undefined
-# BASE_DIRS is handled the same way as for the target_sources().
+# directory path for private header files. It cannot end with slahes❗ If it's empty or
+# undefined, an empty string will be passed to the target_sources(BASE_DIRS). It's handled
+# the same way as for the target_sources().
 #
 # Obtain header and source files (ignoring private headers) and add source files
 # for the given target.
 #
 # Synopsis:
 # tiny_target_sources(<target>
-#   [PRIVATE] PREFIX <name> BASE_DIR <dir>
+#   [PRIVATE] PREFIX <name>
+#   [BASE_DIR [<dir>]]
 # )
 #
-# PRIVATE add obtained headers from the tinyxyz_sources() function as private headers.
-# PREFIX prefix for calling tinyxyz_sources() function to obtain header and source files.
-# Cannot be undefined or empty.
-# BASE_DIR this directory is added to target_include_directories($<BUILD_INTERFACE>).
+# <target> name to operate on.
+# PRIVATE add obtained public headers from the tinyxyz_sources() function as private
+# headers using target_sources(PRIVATE) (especially needed for executables).
+# PREFIX for calling the tinyxyz_sources() function to obtain header and source files.
+# Cannot be empty or undefined.
+# BASE_DIR <dir> is added to the target_include_directories($<BUILD_INTERFACE>).
+# If <dir> is a relative path (cmake_path(IS_RELATIVE) is true), it's evaluated relative
+# to the CMAKE_CURRENT_SOURCE_DIR and normalized. The absolute path stays untouched.
+# If empty or undefined the CMAKE_CURRENT_SOURCE_DIR is used. Symbolic link and tilde
+# is not resolved.
 function(tiny_target_sources target)
 
     # Arguments

cmake/Modules/TinyTestCommon.cmake

@@ -1,6 +1,26 @@
 include_guard(GLOBAL)
 
-# Configure a passed auto test
+# Configure the given test target
+#
+# Synopsis:
+# tiny_configure_test(<target>
+#   [DEPENDS_ON_UNITTESTS]
+#   [INCLUDE_MIGRATIONS] [INCLUDE_MODELS]
+#   [PROVIDES_PCH] [RUN_SERIAL]
+# )
+#
+# <target> name to operate on.
+# DEPENDS_ON_UNITTESTS make the functional test <target> dependent on all unit tests,
+# it should only be enablved for functional tests. Primarily to make functional tests
+# dependent on all unit tests.
+# INCLUDE_MIGRATIONS add migrations headers on the include path and call
+# the target_sources(PRIVATE) for these headers (calls tiny_target_sources(PRIVATE)).
+# INCLUDE_MODELS add models headers on the include path and call
+# the target_sources(PRIVATE) for these headers (calls tiny_target_sources(PRIVATE)).
+# PROVIDES_PCH tag a test <target> that will provide PCH for all other test targets,
+# only one test <target> can be tagged with it and all other test targets will use
+# this PCH without compilation (reuse PCH).
+# RUN_SERIAL set the RUN_SERIAL test property for the <target>.
 function(tiny_configure_test target)
 
     # Arguments