From 263ebed2446637f2ecd45cddca9dd8e427675217 Mon Sep 17 00:00:00 2001
From: Nathan Moinvaziri <nathan@nathanm.com>
Date: Mon, 15 Mar 2021 22:05:58 -0700
Subject: [PATCH] Added comments for cmake test scripts.

---
 cmake/run-and-compare.cmake  | 14 ++++++++++++++
 cmake/run-and-redirect.cmake | 16 ++++++++++++++++
 cmake/test-compress.cmake    | 27 ++++++++++++++++++++++++++-
 3 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/cmake/run-and-compare.cmake b/cmake/run-and-compare.cmake
index 0e934337..d6400520 100644
--- a/cmake/run-and-compare.cmake
+++ b/cmake/run-and-compare.cmake
@@ -1,3 +1,17 @@
+# run-and-compare.cmake -- Runs a command and compares its output to an expected value
+
+# Copyright (C) 2021 Nathan Moinvaziri
+# Licensed under the Zlib license, see LICENSE.md for details
+
+# Required Variables
+#   COMMAND             - Command to run
+#   OUTPUT              - Standard output
+#   COMPARE             - String to compare output against
+
+# Optional Variables
+#   INPUT               - Standard intput
+#   IGNORE_LINE_ENDINGS - Ignore line endings when comparing output
+
 if(NOT DEFINED OUTPUT OR NOT DEFINED COMPARE OR NOT DEFINED COMMAND)
     message(FATAL_ERROR "Run and compare arguments missing")
 endif()
diff --git a/cmake/run-and-redirect.cmake b/cmake/run-and-redirect.cmake
index 30c57411..29f8a33e 100644
--- a/cmake/run-and-redirect.cmake
+++ b/cmake/run-and-redirect.cmake
@@ -1,3 +1,19 @@
+# run-and-redirect.cmake -- Runs a command and validates exit code
+
+# Copyright (C) 2021 Nathan Moinvaziri
+# Licensed under the Zlib license, see LICENSE.md for details
+
+# Normally ctest will always fail with non-zero exit code, but we have tests
+# that need to check specific exit codes.
+
+# Required Variables
+#   COMMAND      - Command to run
+
+# Optional Variables
+#   INPUT        - Standard intput
+#   OUTPUT       - Standard output (default: /dev/null)
+#   SUCCESS_EXIT - List of successful exit codes (default: 0, ie: 0;1)
+
 # If no output is specified, discard output
 if(NOT DEFINED OUTPUT)
     if(WIN32)
diff --git a/cmake/test-compress.cmake b/cmake/test-compress.cmake
index 75355bc7..833aa3fc 100644
--- a/cmake/test-compress.cmake
+++ b/cmake/test-compress.cmake
@@ -1,3 +1,28 @@
+# test-compress.cmake -- Runs a test against an input file to make sure that the specified
+#   targets are able to to compress and then decompress it successfully. Optionally verify
+#   the results with gzip. Output files are generated with unique names to prevent parallel
+#   tests from corrupting one another. Default target arguments are compatible with minigzip.
+
+# Copyright (C) 2021 Nathan Moinvaziri
+# Licensed under the Zlib license, see LICENSE.md for details
+
+# that test a specific input file for compression or decompression.
+
+# Required Variables
+#   INPUT                   - Input file to test
+#   TARGET or               - Command to run for both compress and decompress
+#     COMPRESS_TARGET and   - Command to run to compress input file
+#     DECOMPRESS_TARGET     - Command to run to decompress output file
+
+# Optional Variables
+#   COMPRESS_ARGS           - Arguments to pass for compress command (default: -c -k)
+#   DECOMPRESS_ARGS         - Arguments to pass to decompress command (default: -d -c)
+
+#   GZIP_VERIFY             - Verify that gzip can decompress the COMPRESS_TARGET output and
+#                             verify that DECOMPRESS_TARGET can decompress gzip output of INPUT
+#   COMPARE                 - Verify decompressed output is the same as input
+#   SUCCESS_EXIT            - List of successful exit codes (default: 0, ie: 0;1)
+
 if(TARGET)
     set(COMPRESS_TARGET ${TARGET})
     set(DECOMPRESS_TARGET ${TARGET})
@@ -157,7 +182,7 @@ if(GZIP_VERIFY AND NOT "${COMPRESS_ARGS}" MATCHES "-T")
             message(FATAL_ERROR "Cannot find minigzip decompress input: ${OUTPUT}.gzip.gz")
         endif()
 
-        # Check minigzip can decompress gzip compressed output
+        # Check decompress target can handle gzip compressed output
         execute_process(COMMAND ${CMAKE_COMMAND}
             "-DCOMMAND=${DECOMPRESS_COMMAND}"
             -DINPUT=${OUTPUT}.gzip.gz
-- 
2.47.2