docs(cli): expand exported function documentation for the cli (#696)

packages/cli/index.js

@@ -1,3 +1,2 @@
-export { collectScripts } from "./src/utils.js";
 export { test, mainTestFn } from "./src/testing/index.js";
 export { bench, mainBenchFn } from "./src/benchmarking/index.js";

packages/cli/src/benchmarking/runner.js

@@ -32,8 +32,14 @@ export async function runBenchmarks(state) {
 }
 
 /**
+ * Benchmark entry point. The benchmark runner will wait a bit till now new benchmarks
+ * are registered and then start execution.
+ *
+ * @since 0.1.0
+ *
  * @param {string} name
  * @param {BenchCallback} callback
+ * @returns {undefined}
  */
 export function bench(name, callback) {
   state.push({ name, callback });

packages/cli/src/benchmarking/utils.js

@@ -9,8 +9,15 @@ import {
 } from "./state.js";
 
 /**
- * Wraps `mainFn` and `areBenchRunning
+ * Wraps `mainFn` and starts the benchmark runner if not already started.
+ * By calling this in your bench files, it allows the benchmark file to be directly executed
+ * via `node file.bench.js`. When the runner is already active, this function will be a no
+ * op.
+ *
+ * @since 0.1.0
+ *
  * @param {ImportMeta} meta
+ * @returns {undefined}
  */
 export function mainBenchFn(meta) {
   if (areBenchRunning) {

packages/cli/src/testing/runner.js

@@ -71,9 +71,14 @@ export async function runTestsRecursively(testState) {
 }
 
 /**
+ * Register top-level tests. The main entry point of the test runner
+ *
+ * @since 0.1.0
  * @function
- * @param {string} name
- * @param {TestCallback} callback
+ *
+ * @param {string} name The test name
+ * @param {TestCallback} callback The function that is executed by the test runner. This
+ *    can do async setup, register child tests and run assertions
  * @returns {undefined}
  */
 export const test = subTest.bind(undefined, state);

packages/cli/src/testing/utils.js

@@ -12,8 +12,15 @@ import {
 } from "./state.js";
 
 /**
- * Wraps `mainFn` and `areTestsRunning`
+ * Wraps `mainFn` and starts the test runner if not already started.
+ * By calling this in your test files, it allows the test file to be directly executed
+ * via `node file.test.js`. When the runner is already active, this function will be a no
+ * op.
+ *
+ * @since 0.1.0
+ *
  * @param {ImportMeta} meta
+ * @returns {undefined}
  */
 export function mainTestFn(meta) {
   if (areTestsRunning) {

packages/cli/src/utils.js

@@ -5,7 +5,8 @@ import chokidar from "chokidar";
 import treeKill from "tree-kill";
 
 /**
- * Load scripts directory and package.json scripts
+ * Load scripts directory and package.json scripts.
+ *
  * @returns {ScriptCollection}
  */
 export function collectScripts() {