typings: add JSDoc types to lib/path

PR-URL: #38186
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

Author: Skn0tt

lib/path.js

@@ -112,6 +112,17 @@ function normalizeString(path, allowAboveRoot, separator, isPathSeparator) {
   return res;
 }
 
+/**
+ * @param {string} sep
+ * @param {{
+ *  dir?: string;
+ *  root?: string;
+ *  base?: string;
+ *  name?: string;
+ *  ext?: string;
+ *  }} pathObject
+ * @returns {string}
+ */
 function _format(sep, pathObject) {
   if (pathObject === null || typeof pathObject !== 'object') {
     throw new ERR_INVALID_ARG_TYPE('pathObject', 'Object', pathObject);
@@ -126,7 +137,11 @@ function _format(sep, pathObject) {
 }
 
 const win32 = {
-  // path.resolve([from ...], to)
+  /**
+   * path.resolve([from ...], to)
+   * @param {...string} args
+   * @returns {string}
+   */
   resolve(...args) {
     let resolvedDevice = '';
     let resolvedTail = '';
@@ -262,6 +277,10 @@ const win32 = {
       `${resolvedDevice}${resolvedTail}` || '.';
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   normalize(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -349,6 +368,10 @@ const win32 = {
     return isAbsolute ? `${device}\\${tail}` : `${device}${tail}`;
   },
 
+  /**
+   * @param {string} path
+   * @returns {boolean}
+   */
   isAbsolute(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -364,6 +387,10 @@ const win32 = {
       isPathSeparator(path.charCodeAt(2)));
   },
 
+  /**
+   * @param {...string} args
+   * @returns {string}
+   */
   join(...args) {
     if (args.length === 0)
       return '.';
@@ -429,10 +456,15 @@ const win32 = {
     return win32.normalize(joined);
   },
 
-  // It will solve the relative path from `from` to `to`, for instance:
-  //  from = 'C:\\orandea\\test\\aaa'
-  //  to = 'C:\\orandea\\impl\\bbb'
-  // The output of the function should be: '..\\..\\impl\\bbb'
+  /**
+   * It will solve the relative path from `from` to `to`, for instancee
+   * from = 'C:\\orandea\\test\\aaa'
+   * to = 'C:\\orandea\\impl\\bbb'
+   * The output of the function should be: '..\\..\\impl\\bbb'
+   * @param {string} from
+   * @param {string} to
+   * @returns {string}
+   */
   relative(from, to) {
     validateString(from, 'from');
     validateString(to, 'to');
@@ -579,6 +611,10 @@ const win32 = {
     return path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   dirname(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -665,6 +701,11 @@ const win32 = {
     return path.slice(0, end);
   },
 
+  /**
+   * @param {string} path
+   * @param {string} [ext]
+   * @returns {string}
+   */
   basename(path, ext) {
     if (ext !== undefined)
       validateString(ext, 'ext');
@@ -748,6 +789,10 @@ const win32 = {
     return path.slice(start, end);
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   extname(path) {
     validateString(path, 'path');
     let start = 0;
@@ -814,6 +859,16 @@ const win32 = {
 
   format: _format.bind(null, '\\'),
 
+  /**
+   * @param {string} path
+   * @returns {{
+   *  dir: string;
+   *  root: string;
+   *  base: string;
+   *  name: string;
+   *  ext: string;
+   *  }}
+   */
   parse(path) {
     validateString(path, 'path');
 
@@ -969,7 +1024,11 @@ const win32 = {
 };
 
 const posix = {
-  // path.resolve([from ...], to)
+  /**
+   * path.resolve([from ...], to)
+   * @param {...string} args
+   * @returns {string}
+   */
   resolve(...args) {
     let resolvedPath = '';
     let resolvedAbsolute = false;
@@ -1001,6 +1060,10 @@ const posix = {
     return resolvedPath.length > 0 ? resolvedPath : '.';
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   normalize(path) {
     validateString(path, 'path');
 
@@ -1025,11 +1088,19 @@ const posix = {
     return isAbsolute ? `/${path}` : path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {boolean}
+   */
   isAbsolute(path) {
     validateString(path, 'path');
     return path.length > 0 && path.charCodeAt(0) === CHAR_FORWARD_SLASH;
   },
 
+  /**
+   * @param {...string} args
+   * @returns {string}
+   */
   join(...args) {
     if (args.length === 0)
       return '.';
@@ -1049,6 +1120,11 @@ const posix = {
     return posix.normalize(joined);
   },
 
+  /**
+   * @param {string} from
+   * @param {string} to
+   * @returns {string}
+   */
   relative(from, to) {
     validateString(from, 'from');
     validateString(to, 'to');
@@ -1124,6 +1200,10 @@ const posix = {
     return path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   dirname(path) {
     validateString(path, 'path');
     if (path.length === 0)
@@ -1150,6 +1230,11 @@ const posix = {
     return path.slice(0, end);
   },
 
+  /**
+   * @param {string} path
+   * @param {string} [ext]
+   * @returns {string}
+   */
   basename(path, ext) {
     if (ext !== undefined)
       validateString(ext, 'ext');
@@ -1225,6 +1310,10 @@ const posix = {
     return path.slice(start, end);
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   extname(path) {
     validateString(path, 'path');
     let startDot = -1;
@@ -1279,6 +1368,16 @@ const posix = {
 
   format: _format.bind(null, '/'),
 
+  /**
+   * @param {string} path
+   * @returns {{
+   *   dir: string;
+   *   root: string;
+   *   base: string;
+   *   name: string;
+   *   ext: string;
+   *   }}
+   */
   parse(path) {
     validateString(path, 'path');