docs: add comprehensive docstring to pr-check script

Signed-off-by: Dominiq Barbero <mr.dom.barbero@gmail.com>

Author: MrMadHatt

.github/scripts/pr-check-test-files.sh

@@ -1,4 +1,39 @@
 #!/usr/bin/env bash
+
+# ======================================================================================================================================================
+# @file: pr-check-test-files.sh
+#
+# @Description A CI check written in bash that enforces the '_test.py' suffix, ensures Pytest can automatically discover 
+#               new or renamed test files in a Pull Request. 
+# 
+# @logic: 
+# 1. Identifies files as (A) Added, (R) Renamed, or (C) copied using 'git diff' to check destination filename ($file2). 
+# 2. Validates paths against allowed test directories (unit/integration).
+# 3. Excludes specific utility (ex., conftest.py, utils.py) and non-Python files.
+# 4. Parses tab-separated Git output via IFS=$'\t' to ensure robust filename handling.
+# 5. Routes files using 'case'. Checks $status before dispatching to the proper path.
+#
+# @types:
+# - String: Used for file paths and git status codes. 
+# - Array: Used for 'TEST_DIRS', 'EXCEPTION_NAMES', and accumulating errors.
+#
+# @Parameters:
+# - None: This script does not accept CLI arguments. It derives the input from the current Git state compared against origin/main.
+#  
+# @Dependencies:
+# - Git: (for diff)
+# - Bash: (runs the script)
+# - Pytest: (naming standard)
+#
+# @Permissions:
+# - Requires Execute permissions (chmod +x) to run. Also needs Read access to the git repository to perform the diff.
+#
+# @Return
+# - 0: All test files follow the naming standard.
+# - 1: Returns a RED error output identifying the specific file that's receiving the error.
+#      Includes a yellow instructional block providing reason why the file failed.
+# ======================================================================================================================================================
+
 RED="\033[31m"
 YELLOW="\033[33m"
 RESET="\033[0m"