Add `doc.odin` and mention the defineables through `#config`

3 files changed, 60 insertions, 15 deletions

diff --git a/core/testing/doc.odin b/core/testing/doc.odin
new file mode 100644
index 000000000..85dc80cc3
--- /dev/null
+++ b/core/testing/doc.odin
@@ -0,0 +1,46 @@
+/*
+The implementation of the `odin test` runner and procedures user tests can use for this purpose.
+
+Defineables through `#config`:
+
+```odin
+// Specify how many threads to use when running tests.
+TEST_THREADS          : int    : #config(ODIN_TEST_THREADS,              0)
+// Track the memory used by each test.
+TRACKING_MEMORY       : bool   : #config(ODIN_TEST_TRACK_MEMORY,         true)
+// Always report how much memory is used, even when there are no leaks or bad frees.
+ALWAYS_REPORT_MEMORY  : bool   : #config(ODIN_TEST_ALWAYS_REPORT_MEMORY, false)
+// Treat memory leaks and bad frees as errors.
+FAIL_ON_BAD_MEMORY    : bool   : #config(ODIN_TEST_FAIL_ON_BAD_MEMORY,   false)
+// Specify how much memory each thread allocator starts with.
+PER_THREAD_MEMORY     : int    : #config(ODIN_TEST_THREAD_MEMORY, mem.   ROLLBACK_STACK_DEFAULT_BLOCK_SIZE)
+// Select a specific set of tests to run by name.
+// Each test is separated by a comma and may optionally include the package name.
+// This may be useful when running tests on multiple packages with `-all-packages`.
+// The format is: `package.test_name,test_name_only,...`
+TEST_NAMES            : string : #config(ODIN_TEST_NAMES,                "")
+// Show the fancy animated progress report.
+// This requires terminal color support, as well as STDOUT to not be redirected to a file.
+FANCY_OUTPUT          : bool   : #config(ODIN_TEST_FANCY,                true)
+// Copy failed tests to the clipboard when done.
+USE_CLIPBOARD         : bool   : #config(ODIN_TEST_CLIPBOARD,            false)
+// How many test results to show at a time per package.
+PROGRESS_WIDTH        : int    : #config(ODIN_TEST_PROGRESS_WIDTH,       24)
+// This is the random seed that will be sent to each test.
+// If it is unspecified, it will be set to the system cycle counter at startup.
+SHARED_RANDOM_SEED    : u64    : #config(ODIN_TEST_RANDOM_SEED,          0)
+// Set the lowest log level for this test run.
+LOG_LEVEL_DEFAULT     : string : "debug" when ODIN_DEBUG else "info"
+LOG_LEVEL             : string : #config(ODIN_TEST_LOG_LEVEL,            LOG_LEVEL_DEFAULT)
+// Report a message at the info level when a test has changed its state.
+LOG_STATE_CHANGES     : bool   : #config(ODIN_TEST_LOG_STATE_CHANGES,    false)
+// Show only the most necessary logging information.
+USING_SHORT_LOGS      : bool   : #config(ODIN_TEST_SHORT_LOGS,           false)
+// Output a report of the tests to the given path.
+JSON_REPORT           : string : #config(ODIN_TEST_JSON_REPORT,          "")
+// Print the full file path for failed test cases on a new line
+// in a way that's friendly to regex capture for an editor's "go to error".
+GO_TO_ERROR           : bool   : #config(ODIN_TEST_GO_TO_ERROR,          false)
+```
+*/
+package testing
\ No newline at end of file
diff --git a/core/testing/runner.odin b/core/testing/runner.odin
index e0a37c46d..03115b165 100644
--- a/core/testing/runner.odin
+++ b/core/testing/runner.odin
@@ -30,42 +30,42 @@ import "core:thread"
 import "core:time"
 
 // Specify how many threads to use when running tests.
-TEST_THREADS          : int    : #config(ODIN_TEST_THREADS, 0)
+TEST_THREADS          : int    : #config(ODIN_TEST_THREADS,              0)
 // Track the memory used by each test.
-TRACKING_MEMORY       : bool   : #config(ODIN_TEST_TRACK_MEMORY, true)
+TRACKING_MEMORY       : bool   : #config(ODIN_TEST_TRACK_MEMORY,         true)
 // Always report how much memory is used, even when there are no leaks or bad frees.
 ALWAYS_REPORT_MEMORY  : bool   : #config(ODIN_TEST_ALWAYS_REPORT_MEMORY, false)
 // Treat memory leaks and bad frees as errors.
-FAIL_ON_BAD_MEMORY    : bool   : #config(ODIN_TEST_FAIL_ON_BAD_MEMORY, false)
+FAIL_ON_BAD_MEMORY    : bool   : #config(ODIN_TEST_FAIL_ON_BAD_MEMORY,   false)
 // Specify how much memory each thread allocator starts with.
-PER_THREAD_MEMORY     : int    : #config(ODIN_TEST_THREAD_MEMORY, mem.ROLLBACK_STACK_DEFAULT_BLOCK_SIZE)
+PER_THREAD_MEMORY     : int    : #config(ODIN_TEST_THREAD_MEMORY, mem.   ROLLBACK_STACK_DEFAULT_BLOCK_SIZE)
 // Select a specific set of tests to run by name.
 // Each test is separated by a comma and may optionally include the package name.
 // This may be useful when running tests on multiple packages with `-all-packages`.
 // The format is: `package.test_name,test_name_only,...`
-TEST_NAMES            : string : #config(ODIN_TEST_NAMES, "")
+TEST_NAMES            : string : #config(ODIN_TEST_NAMES,                "")
 // Show the fancy animated progress report.
 // This requires terminal color support, as well as STDOUT to not be redirected to a file.
-FANCY_OUTPUT          : bool   : #config(ODIN_TEST_FANCY, true)
+FANCY_OUTPUT          : bool   : #config(ODIN_TEST_FANCY,                true)
 // Copy failed tests to the clipboard when done.
-USE_CLIPBOARD         : bool   : #config(ODIN_TEST_CLIPBOARD, false)
+USE_CLIPBOARD         : bool   : #config(ODIN_TEST_CLIPBOARD,            false)
 // How many test results to show at a time per package.
-PROGRESS_WIDTH        : int    : #config(ODIN_TEST_PROGRESS_WIDTH, 24)
+PROGRESS_WIDTH        : int    : #config(ODIN_TEST_PROGRESS_WIDTH,       24)
 // This is the random seed that will be sent to each test.
 // If it is unspecified, it will be set to the system cycle counter at startup.
-SHARED_RANDOM_SEED    : u64    : #config(ODIN_TEST_RANDOM_SEED, 0)
+SHARED_RANDOM_SEED    : u64    : #config(ODIN_TEST_RANDOM_SEED,          0)
 // Set the lowest log level for this test run.
 LOG_LEVEL_DEFAULT     : string : "debug" when ODIN_DEBUG else "info"
-LOG_LEVEL             : string : #config(ODIN_TEST_LOG_LEVEL, LOG_LEVEL_DEFAULT)
+LOG_LEVEL             : string : #config(ODIN_TEST_LOG_LEVEL,            LOG_LEVEL_DEFAULT)
 // Report a message at the info level when a test has changed its state.
-LOG_STATE_CHANGES     : bool   : #config(ODIN_TEST_LOG_STATE_CHANGES, false)
+LOG_STATE_CHANGES     : bool   : #config(ODIN_TEST_LOG_STATE_CHANGES,    false)
 // Show only the most necessary logging information.
-USING_SHORT_LOGS      : bool   : #config(ODIN_TEST_SHORT_LOGS, false)
+USING_SHORT_LOGS      : bool   : #config(ODIN_TEST_SHORT_LOGS,           false)
 // Output a report of the tests to the given path.
-JSON_REPORT           : string : #config(ODIN_TEST_JSON_REPORT, "")
+JSON_REPORT           : string : #config(ODIN_TEST_JSON_REPORT,          "")
 // Print the full file path for failed test cases on a new line
 // in a way that's friendly to regex capture for an editor's "go to error".
-GO_TO_ERROR           : bool   : #config(ODIN_TEST_GO_TO_ERROR, false)
+GO_TO_ERROR           : bool   : #config(ODIN_TEST_GO_TO_ERROR,          false)
 
 get_log_level :: #force_inline proc() -> runtime.Logger_Level {
 	when LOG_LEVEL == "debug"   { return .Debug   } else
diff --git a/core/testing/testing.odin b/core/testing/testing.odin
index d6bf6ea33..7182f77f5 100644
--- a/core/testing/testing.odin
+++ b/core/testing/testing.odin
@@ -1,4 +1,3 @@
-// The implementation of the `odin test` runner and procedures user tests can use for this purpose.
 package testing
 
 /*