docs: refine code comments

Signed-off-by: Jérôme Benoit <jerome.benoit@piment-noir.org>

diff --git a/package.json b/package.json
index d501928ce72c2d1d4ec29974fd3e6fbeacdac883..bb2eeeed800e273cd23f3e39c912573ece904cf9 100644 (file)
--- a/package.json
+++ b/package.json
@@ -116,7 +116,7 @@
     "@release-it/keep-a-changelog": "^4.0.0",
     "@rollup/plugin-terser": "^0.4.3",
     "@rollup/plugin-typescript": "^11.1.3",
-    "@types/node": "^20.5.8",
+    "@types/node": "^20.5.9",
     "@typescript-eslint/eslint-plugin": "^6.5.0",
     "@typescript-eslint/parser": "^6.5.0",
     "benny": "^3.7.1",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 87f82e2906db17fe1a4cc793c0e6fc8f188b227d..bb615bf4a7b980f57d3a2b3a3d9d01983b4ba8cc 100644 (file)
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -27,8 +27,8 @@ devDependencies:
     specifier: ^11.1.3
     version: 11.1.3(rollup@3.28.1)(typescript@5.2.2)
   '@types/node':
-    specifier: ^20.5.8
-    version: 20.5.8
+    specifier: ^20.5.9
+    version: 20.5.9
   '@typescript-eslint/eslint-plugin':
     specifier: ^6.5.0
     version: 6.5.0(@typescript-eslint/parser@6.5.0)(eslint@8.48.0)(typescript@5.2.2)
@@ -284,13 +284,13 @@ packages:
       '@commitlint/types': 17.4.4
       '@types/node': 20.4.7
       chalk: 4.1.2
-      cosmiconfig: 8.2.0
-      cosmiconfig-typescript-loader: 4.4.0(@types/node@20.4.7)(cosmiconfig@8.2.0)(ts-node@10.9.1)(typescript@5.2.2)
+      cosmiconfig: 8.3.2(typescript@5.2.2)
+      cosmiconfig-typescript-loader: 4.4.0(@types/node@20.4.7)(cosmiconfig@8.3.2)(ts-node@10.9.1)(typescript@5.2.2)
       lodash.isplainobject: 4.0.6
       lodash.merge: 4.6.2
       lodash.uniq: 4.5.0
       resolve-from: 5.0.0
-      ts-node: 10.9.1(@types/node@20.5.8)(typescript@5.2.2)
+      ts-node: 10.9.1(@types/node@20.5.9)(typescript@5.2.2)
       typescript: 5.2.2
     transitivePeerDependencies:
       - '@swc/core'
@@ -467,7 +467,7 @@ packages:
       '@jest/schemas': 29.6.3
       '@types/istanbul-lib-coverage': 2.0.4
       '@types/istanbul-reports': 3.0.1
-      '@types/node': 20.5.8
+      '@types/node': 20.5.9
       '@types/yargs': 17.0.24
       chalk: 4.1.2
     dev: true
@@ -898,7 +898,7 @@ packages:
     resolution: {integrity: sha512-ZUxbzKl0IfJILTS6t7ip5fQQM/J3TJYubDm3nMbgubNNYS62eXeUpoLUC8/7fJNiFYHTrGPQn7hspDUzIHX3UA==}
     dependencies:
       '@types/minimatch': 5.1.2
-      '@types/node': 20.5.8
+      '@types/node': 20.5.9
     dev: true
 
   /@types/http-cache-semantics@4.0.1:
@@ -941,8 +941,8 @@ packages:
     resolution: {integrity: sha512-bUBrPjEry2QUTsnuEjzjbS7voGWCc30W0qzgMf90GPeDGFRakvrz47ju+oqDAKCXLUCe39u57/ORMl/O/04/9g==}
     dev: true
 
-  /@types/node@20.5.8:
-    resolution: {integrity: sha512-eajsR9aeljqNhK028VG0Wuw+OaY5LLxYmxeoXynIoE6jannr9/Ucd1LL0hSSoafk5LTYG+FfqsyGt81Q6Zkybw==}
+  /@types/node@20.5.9:
+    resolution: {integrity: sha512-PcGNd//40kHAS3sTlzKB9C9XL4K0sTup8nbG5lC14kzEteTNuAFh9u5nA0o5TWnSG2r/JNPRXFVcHJIIeRlmqQ==}
     dev: true
 
   /@types/normalize-package-data@2.4.1:
@@ -1939,7 +1939,7 @@ packages:
     resolution: {integrity: sha512-ASFBup0Mz1uyiIjANan1jzLQami9z1PoYSZCiiYW2FczPbenXc45FZdBZLzOT+r6+iciuEModtmCti+hjaAk0A==}
     dev: true
 
-  /cosmiconfig-typescript-loader@4.4.0(@types/node@20.4.7)(cosmiconfig@8.2.0)(ts-node@10.9.1)(typescript@5.2.2):
+  /cosmiconfig-typescript-loader@4.4.0(@types/node@20.4.7)(cosmiconfig@8.3.2)(ts-node@10.9.1)(typescript@5.2.2):
     resolution: {integrity: sha512-BabizFdC3wBHhbI4kJh0VkQP9GkBfoHPydD0COMce1nJ1kJAB3F2TmJ/I7diULBKtmEWSwEbuN/KDtgnmUUVmw==}
     engines: {node: '>=v14.21.3'}
     peerDependencies:
@@ -1949,8 +1949,8 @@ packages:
       typescript: '>=4'
     dependencies:
       '@types/node': 20.4.7
-      cosmiconfig: 8.2.0
-      ts-node: 10.9.1(@types/node@20.5.8)(typescript@5.2.2)
+      cosmiconfig: 8.3.2(typescript@5.2.2)
+      ts-node: 10.9.1(@types/node@20.5.9)(typescript@5.2.2)
       typescript: 5.2.2
     dev: true
 
@@ -1964,6 +1964,22 @@ packages:
       path-type: 4.0.0
     dev: true
 
+  /cosmiconfig@8.3.2(typescript@5.2.2):
+    resolution: {integrity: sha512-/PvU3MjSLVKJMRHsL6GW+wHQ9RaJuMW6fnn56sXNy+kP1L8nI/SHk9F9giIA+dnfzjKNJAulRjOR/fi9kzGuNA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+    dependencies:
+      import-fresh: 3.3.0
+      js-yaml: 4.1.0
+      parse-json: 5.2.0
+      path-type: 4.0.0
+      typescript: 5.2.2
+    dev: true
+
   /create-require@1.1.1:
     resolution: {integrity: sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==}
     dev: true
@@ -4035,7 +4051,7 @@ packages:
     engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
     dependencies:
       '@jest/types': 29.6.3
-      '@types/node': 20.5.8
+      '@types/node': 20.5.9
       chalk: 4.1.2
       ci-info: 3.8.0
       graceful-fs: 4.2.11
@@ -6029,7 +6045,7 @@ packages:
       typescript: 5.2.2
     dev: true
 
-  /ts-node@10.9.1(@types/node@20.5.8)(typescript@5.2.2):
+  /ts-node@10.9.1(@types/node@20.5.9)(typescript@5.2.2):
     resolution: {integrity: sha512-NtVysVPkxxrwFGUUxGYhfux8k78pQB3JqYBXlLRZgdGUqTO5wU/UyHop5p70iEbGhB7q5KmiZiU0Y3KlJrScEw==}
     hasBin: true
     peerDependencies:
@@ -6048,7 +6064,7 @@ packages:
       '@tsconfig/node12': 1.0.11
       '@tsconfig/node14': 1.0.3
       '@tsconfig/node16': 1.0.4
-      '@types/node': 20.5.8
+      '@types/node': 20.5.9
       acorn: 8.10.0
       acorn-walk: 8.2.0
       arg: 4.1.3

diff --git a/src/pools/worker.ts b/src/pools/worker.ts
index 5a351df0920244400082391b8d0c0680eb32f7a3..29050455088c6efd49d8147aed07c41f2a5a004e 100644 (file)
--- a/src/pools/worker.ts
+++ b/src/pools/worker.ts
@@ -173,6 +173,8 @@ export interface WorkerUsage {
 
 /**
  * Worker choice strategy data.
+ *
+ * @internal
  */
 export interface StrategyData {
   virtualTaskEndTimestamp?: number

diff --git a/src/utils.ts b/src/utils.ts
index 21cf3169b73040967bd856bc69e4a311cede6bf5..86b6edadf5da05a139d872202675e1ebda47f3f1 100644 (file)
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -52,7 +52,6 @@ export const DEFAULT_MEASUREMENT_STATISTICS_REQUIREMENTS: MeasurementStatisticsR
  * Always returns a value greater than zero.
  *
  * @returns The host OS optimized maximum pool size.
- * @internal
  */
 export const availableParallelism = (): number => {
   let availableParallelism = 1
@@ -102,6 +101,7 @@ export const getWorkerId = (worker: IWorker): number | undefined => {
  *
  * @param ms - The amount of milliseconds to sleep.
  * @returns A promise that resolves after the given amount of milliseconds.
+ * @internal
  */
 export const sleep = async (ms: number): Promise<void> => {
   await new Promise((resolve) => {
@@ -175,6 +175,7 @@ export const median = (dataSet: number[]): number => {
  * @param num - The number to round.
  * @param scale - The scale to round to.
  * @returns The rounded number.
+ * @internal
  */
 export const round = (num: number, scale = 2): number => {
   const rounder = Math.pow(10, scale)
@@ -186,6 +187,7 @@ export const round = (num: number, scale = 2): number => {
  *
  * @param obj - The object to check.
  * @returns `true` if the given object is a plain object, `false` otherwise.
+ * @internal
  */
 export const isPlainObject = (obj: unknown): boolean =>
   typeof obj === 'object' &&
@@ -214,6 +216,7 @@ export const isKillBehavior = <KB extends KillBehavior>(
  *
  * @param fn - Any value.
  * @returns `true` if `fn` was an asynchronous function, otherwise `false`.
+ * @internal
  */
 export const isAsyncFunction = (
   fn: unknown
@@ -266,16 +269,33 @@ export const updateMeasurementStatistics = (
 }
 
 /**
- * Generate a cryptographically secure random number in the [0,1[ range
+ * Generates a cryptographically secure random number in the [0,1[ range
  *
  * @returns A number in the [0,1[ range
+ * @internal
  */
 export const secureRandom = (): number => {
   return webcrypto.getRandomValues(new Uint32Array(1))[0] / 0x100000000
 }
 
+/**
+ * Returns the minimum of the given numbers.
+ * If no numbers are given, `Infinity` is returned.
+ *
+ * @param args - The numbers to get the minimum of.
+ * @returns The minimum of the given numbers.
+ * @internal
+ */
 export const min = (...args: number[]): number =>
   args.reduce((minimum, num) => (minimum < num ? minimum : num), Infinity)
 
+/**
+ * Returns the maximum of the given numbers.
+ * If no numbers are given, `-Infinity` is returned.
+ *
+ * @param args - The numbers to get the maximum of.
+ * @returns The maximum of the given numbers.
+ * @internal
+ */
 export const max = (...args: number[]): number =>
   args.reduce((maximum, num) => (maximum > num ? maximum : num), -Infinity)