GHI #18 Improved documentation in test OptionVariables.cmake

test/cmake/OptionVariables.cmake

@@ -1,3 +1,16 @@
+# ---- Options Summary ----
+
+# --------------------------------------------------------------------
+# | Option                               | Availability | Default    |
+# |======================================|==============|============|
+# | CMAKE_INSTALL_TESTDIR (unofficial)   | Always       | share/test |
+# |--------------------------------------|--------------|------------|
+# | PATOMIC_CREATE_TEST_TARGETS_MATCHING | Always       | ^(.*)$     |
+# | PATOMIC_WINDOWS_SET_CTEST_PATH_ENV   | Always       | ON         |
+# | PATOMIC_WINDOWS_CREATE_PATH_ENV_FILE | Always       | OFF        |
+# --------------------------------------------------------------------
+
+
 # ---- Test Install Directory ----
 
 # Normally tests would be install in CMAKE_INSTALL_BINDIR by default since
@@ -15,8 +28,8 @@ set(
 
 # ---- Test Build Selection ----
 
-# This option provides a way to selectively disable/enable tests based on target
-# name (not suite/case name, or name passed to create_test).
+# This option provides a way to selectively disable/enable building tests based
+# on target name (not suite/case name, or name passed to create_test).
 # Regex must be written according to CMake Regex Specification.
 # By default all test targets are enabled.
 set(
@@ -30,8 +43,9 @@ set(
 # By default we set PATH for tests run with CTest on Windows in order to prevent
 # linker errors.
 # Due to limitations in CMake, we can only completely override the PATH, rather
-# than prepend to it.
+# than prepend or append to it.
 # This gives users the option to disable this behaviour.
+# This option has no effect when not running on Windows.
 option(
     PATOMIC_WINDOWS_SET_CTEST_PATH_ENV
     "Set PATH environment variable for tests when run CTest on Windows"
@@ -42,13 +56,16 @@ mark_as_advanced(PATOMIC_WINDOWS_SET_CTEST_PATH_ENV)
 
 # ---- Windows Path File ----
 
-# By default on Windows we generate a file per test kind that contains a string
-# that can be prepended to PATH before running tests, in order to ensure that
+# On Windows we need to set PATH for tests but may not want to have the PATH be
+# completely overridden, like with PATOMIC_WINDOWS_SET_CTEST_PATH_ENV.
+# Instead we can generated a file per test kind that contains a string that can
+# be manually prepended to PATH before running tests, in order to ensure that
 # runtime dependencies can be found.
 # Most of the time we don't need this file (since CTest will take care of that
-# for us), so we don't need to generate it.
+# for us), so we don't generate it by default.
 # Additionally disabled by default because it contains potentially private
 # information about the target platform.
+# This option has no effect when not running on Windows.
 option(
     PATOMIC_WINDOWS_CREATE_PATH_ENV_FILE
     "Create file with PATH environment variables for tests on Windows"