lib: add JSDoc typings for child_process

Added JSDoc typings for the `child_process` lib module. PR-URL: #38222 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com>
nodejs · Jun 21, 2021 · 5514305 · 5514305
1 parent dce256b
commit 5514305
Showing 1 changed file with 161 additions and 4 deletions.
diff --git a/lib/child_process.js b/lib/child_process.js
@@ -89,6 +89,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');
 
@@ -176,7 +198,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,
@@ -207,6 +251,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;
@@ -596,7 +665,28 @@ function abortChildProcess(child, killSignal) {
   }
 }
 
-
+/**
+ * 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) {
   options = normalizeSpawnArguments(file, args, options);
   validateTimeout(options.timeout);
@@ -645,6 +735,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,
@@ -711,7 +831,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);
 
@@ -730,7 +869,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;