From acba7c4013c55c8a5bf0775a8c16e50bbc36964b 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 bdf24983e56503..fed8fc5e969174 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -10,7 +10,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
@@ -31,7 +31,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) {
   /**
@@ -63,7 +63,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');
@@ -78,7 +78,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 {
@@ -96,7 +96,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 882fc9f92bd3ec..5cebbe0860d085 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -141,12 +141,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,
@@ -159,6 +167,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.