From aadfea49798ea1fbab43f6e7051de8701f0be7b5 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 1 Oct 2023 08:26:56 +0100
Subject: [PATCH] esm: improve JSDoc annotation of internal functions

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>
PR-URL: https://github.com/nodejs/node/pull/49959
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
---
 lib/internal/modules/run_main.js      | 11 ++++++-----
 lib/internal/process/pre_execution.js | 10 ++++++++++
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index e5969bf7b75ea6..0b58d348203bfe 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -9,7 +9,7 @@ const path = require('path');
 
 /**
  * Get the absolute path to the main entry point.
- * @param {string} main Entry point path
+ * @param {string} main - Entry point path
  */
 function resolveMainPath(main) {
   // Note extension resolution for the main entry point can be deprecated in a
@@ -30,7 +30,7 @@ function resolveMainPath(main) {
 
 /**
  * Determine whether the main entry point should be loaded through the ESM Loader.
- * @param {string} mainPath Absolute path to the main entry point
+ * @param {string} mainPath - Absolute path to the main entry point
  */
 function shouldUseESMLoader(mainPath) {
   /**
@@ -57,7 +57,7 @@ function shouldUseESMLoader(mainPath) {
 
 /**
  * Run the main entry point through the ESM Loader.
- * @param {string} mainPath Absolute path to the main entry point
+ * @param {string} mainPath - Absolute path for the main entry point
  */
 function runMainESM(mainPath) {
   const { loadESM } = require('internal/process/esm_loader');
@@ -72,7 +72,7 @@ function runMainESM(mainPath) {
 
 /**
  * Handle process exit events around the main entry point promise.
- * @param {Promise} promise Main entry point promise
+ * @param {Promise} promise - Main entry point promise
  */
 async function handleMainPromise(promise) {
   const {
@@ -90,7 +90,8 @@ async function handleMainPromise(promise) {
  * Parse the CLI main entry point string and run it.
  * For backwards compatibility, we have to run a bunch of monkey-patchable code that belongs to the CJS loader (exposed
  * by `require('module')`) even when the entry point is ESM.
- * @param {string} main CLI main entry point string
+ * Because of backwards compatibility, this function is exposed publicly via `import { runMain } from 'node:module'`.
+ * @param {string} main - Resolved absolute path for the main entry point, if found
  */
 function executeUserEntryPoint(main = process.argv[1]) {
   const resolvedMain = resolveMainPath(main);
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 2be86f907bd47c..d066d12a553d6f 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -176,12 +176,20 @@ function refreshRuntimeOptions() {
   refreshOptions();
 }
 
+/**
+ * Patch the process object with legacy properties and normalizations.
+ * Replace `process.argv[0]` with `process.execPath`, preserving the original `argv[0]` value as `process.argv0`.
+ * Replace `process.argv[1]` with the resolved absolute file path of the entry point, if found.
+ * @param {boolean} expandArgv1 - Whether to replace `process.argv[1]` with the resolved absolute file path of
+ * the main entry point.
+ */
 function patchProcessObject(expandArgv1) {
   const binding = internalBinding('process_methods');
   binding.patchProcessObject(process);
 
   require('internal/process/per_thread').refreshHrtimeBuffer();
 
+  // Since we replace process.argv[0] below, preserve the original value in case the user needs it.
   ObjectDefineProperty(process, 'argv0', {
     __proto__: null,
     enumerable: true,
@@ -194,6 +202,8 @@ function patchProcessObject(expandArgv1) {
   process._exiting = false;
   process.argv[0] = process.execPath;
 
+  // If requested, update process.argv[1] to replace whatever the user provided with the resolved absolute file path of
+  // the entry point.
   if (expandArgv1 && process.argv[1] &&
       !StringPrototypeStartsWith(process.argv[1], '-')) {
     // Expand process.argv[1] into a full path.