From 2bc2a232af5bb1feeebbac311e6ffced41e2981c Mon Sep 17 00:00:00 2001
From: Voltrex <62040526+VoltrexMaster@users.noreply.github.com>
Date: Tue, 13 Apr 2021 05:31:10 +0430
Subject: [PATCH] lib: add JSDoc typings for child_process

Added JSDoc typings for the `child_process` lib module.

PR-URL: https://github.com/nodejs/node/pull/38222
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
---
 lib/child_process.js | 164 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 161 insertions(+), 3 deletions(-)

diff --git a/lib/child_process.js b/lib/child_process.js
index 68fb8ddd3d254a..a9c44e12e87f11 100644
--- a/lib/child_process.js
+++ b/lib/child_process.js
@@ -74,6 +74,28 @@ const {
 
 const MAX_BUFFER = 1024 * 1024;
 
+/**
+ * Spawns a new Node.js process + fork.
+ * @param {string} modulePath
+ * @param {string[]} [args]
+ * @param {{
+ *   cwd?: string;
+ *   detached?: boolean;
+ *   env?: Object;
+ *   execPath?: string;
+ *   execArgv?: string[];
+ *   gid?: number;
+ *   serialization?: string;
+ *   signal?: AbortSignal;
+ *   killSignal?: string | number;
+ *   silent?: boolean;
+ *   stdio?: Array | string;
+ *   uid?: number;
+ *   windowsVerbatimArguments?: boolean;
+ *   timeout?: number;
+ *   }} [options]
+ * @returns {ChildProcess}
+ */
 function fork(modulePath /* , args, options */) {
   validateString(modulePath, 'modulePath');
 
@@ -161,7 +183,29 @@ function normalizeExecArgs(command, options, callback) {
   };
 }
 
-
+/**
+ * Spawns a shell executing the given command.
+ * @param {string} command
+ * @param {{
+ *   cmd?: string;
+ *   env?: Object;
+ *   encoding?: string;
+ *   shell?: string;
+ *   signal?: AbortSignal;
+ *   timeout?: number;
+ *   maxBuffer?: number;
+ *   killSignal?: string | number;
+ *   uid?: number;
+ *   gid?: number;
+ *   windowsHide?: boolean;
+ *   }} [options]
+ * @param {(
+ *   error?: Error,
+ *   stdout?: string | Buffer,
+ *   stderr?: string | Buffer
+ *   ) => any} [callback]
+ * @returns {ChildProcess}
+ */
 function exec(command, options, callback) {
   const opts = normalizeExecArgs(command, options, callback);
   return module.exports.execFile(opts.file,
@@ -197,6 +241,31 @@ ObjectDefineProperty(exec, promisify.custom, {
   value: customPromiseExecFunction(exec)
 });
 
+/**
+ * Spawns the specified file as a shell.
+ * @param {string} file
+ * @param {string[]} [args]
+ * @param {{
+ *   cwd?: string;
+ *   env?: Object;
+ *   encoding?: string;
+ *   timeout?: number;
+ *   maxBuffer?: number;
+ *   killSignal?: string | number;
+ *   uid?: number;
+ *   gid?: number;
+ *   windowsHide?: boolean;
+ *   windowsVerbatimArguments?: boolean;
+ *   shell?: boolean | string;
+ *   signal?: AbortSignal;
+ *   }} [options]
+ * @param {(
+ *   error?: Error,
+ *   stdout?: string | Buffer,
+ *   stderr?: string | Buffer
+ *   ) => any} [callback]
+ * @returns {ChildProcess}
+ */
 function execFile(file /* , args, options, callback */) {
   let args = [];
   let callback;
@@ -567,6 +636,28 @@ function normalizeSpawnArguments(file, args, options) {
 }
 
 
+/**
+ * Spawns a new process using the given `file`.
+ * @param {string} file
+ * @param {string[]} [args]
+ * @param {{
+ *   cwd?: string;
+ *   env?: Object;
+ *   argv0?: string;
+ *   stdio?: Array | string;
+ *   detached?: boolean;
+ *   uid?: number;
+ *   gid?: number;
+ *   serialization?: string;
+ *   shell?: boolean | string;
+ *   windowsVerbatimArguments?: boolean;
+ *   windowsHide?: boolean;
+ *   signal?: AbortSignal;
+ *   timeout?: number;
+ *   killSignal?: string | number;
+ *   }} [options]
+ * @returns {ChildProcess}
+ */
 function spawn(file, args, options) {
   const child = new ChildProcess();
 
@@ -577,6 +668,36 @@ function spawn(file, args, options) {
   return child;
 }
 
+/**
+ * Spawns a new process synchronously using the given `file`.
+ * @param {string} file
+ * @param {string[]} [args]
+ * @param {{
+ *   cwd?: string;
+ *   input?: string | Buffer | TypedArray | DataView;
+ *   argv0?: string;
+ *   stdio?: string | Array;
+ *   env?: Object;
+ *   uid?: number;
+ *   gid?: number;
+ *   timeout?: number;
+ *   killSignal?: string | number;
+ *   maxBuffer?: number;
+ *   encoding?: string;
+ *   shell?: boolean | string;
+ *   windowsVerbatimArguments?: boolean;
+ *   windowsHide?: boolean;
+ *   }} [options]
+ * @returns {{
+ *   pid: number;
+ *   output: Array;
+ *   stdout: Buffer | string;
+ *   stderr: Buffer | string;
+ *   status: number | null;
+ *   signal: string | null;
+ *   error: Error;
+ *   }}
+ */
 function spawnSync(file, args, options) {
   options = {
     maxBuffer: MAX_BUFFER,
@@ -643,7 +764,26 @@ function checkExecSyncError(ret, args, cmd) {
   return err;
 }
 
-
+/**
+ * Spawns a file as a shell synchronously.
+ * @param {string} command
+ * @param {string[]} [args]
+ * @param {{
+ *   cwd?: string;
+ *   input?: string | Buffer | TypedArray | DataView;
+ *   stdio?: string | Array;
+ *   env?: Object;
+ *   uid?: number;
+ *   gid?: number;
+ *   timeout?: number;
+ *   killSignal?: string | number;
+ *   maxBuffer?: number;
+ *   encoding?: string;
+ *   windowsHide?: boolean;
+ *   shell?: boolean | string;
+ *   }} [options]
+ * @returns {Buffer | string}
+ */
 function execFileSync(command, args, options) {
   options = normalizeSpawnArguments(command, args, options);
 
@@ -661,7 +801,25 @@ function execFileSync(command, args, options) {
   return ret.stdout;
 }
 
-
+/**
+ * Spawns a shell executing the given `command` synchronously.
+ * @param {string} command
+ * @param {{
+ *   cwd?: string;
+ *   input?: string | Buffer | TypedArray | DataView;
+ *   stdio?: string | Array;
+ *   env?: Object;
+ *   shell?: string;
+ *   uid?: number;
+ *   gid?: number;
+ *   timeout?: number;
+ *   killSignal?: string | number;
+ *   maxBuffer?: number;
+ *   encoding?: string;
+ *   windowsHide?: boolean;
+ *   }} [options]
+ * @returns {Buffer | string}
+ */
 function execSync(command, options) {
   const opts = normalizeExecArgs(command, options, null);
   const inheritStderr = !opts.options.stdio;