From f1a21e5c914f9bcbbb2a77b436eae2bc4f4c2a86 Mon Sep 17 00:00:00 2001
From: Simon Knott <info@simonknott.de>
Date: Sat, 10 Apr 2021 11:12:35 +0200
Subject: [PATCH] typings: add JSDoc types to lib/path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/38186
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
---
 lib/path.js | 111 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 105 insertions(+), 6 deletions(-)

diff --git a/lib/path.js b/lib/path.js
index 9689827549978f..f3e5a3b3416c4b 100644
--- a/lib/path.js
+++ b/lib/path.js
@@ -127,6 +127,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) {
   validateObject(pathObject, 'pathObject');
   const dir = pathObject.dir || pathObject.root;
@@ -139,7 +150,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 = '';
@@ -282,6 +297,10 @@ const win32 = {
       `${resolvedDevice}${resolvedTail}` || '.';
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   normalize(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -376,6 +395,10 @@ const win32 = {
     return isAbsolute ? `${device}\\${tail}` : `${device}${tail}`;
   },
 
+  /**
+   * @param {string} path
+   * @returns {boolean}
+   */
   isAbsolute(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -391,6 +414,10 @@ const win32 = {
       isPathSeparator(StringPrototypeCharCodeAt(path, 2)));
   },
 
+  /**
+   * @param {...string} args
+   * @returns {string}
+   */
   join(...args) {
     if (args.length === 0)
       return '.';
@@ -457,10 +484,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');
@@ -618,6 +650,10 @@ const win32 = {
     return path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   dirname(path) {
     validateString(path, 'path');
     const len = path.length;
@@ -709,6 +745,11 @@ const win32 = {
     return StringPrototypeSlice(path, 0, end);
   },
 
+  /**
+   * @param {string} path
+   * @param {string} [ext]
+   * @returns {string}
+   */
   basename(path, ext) {
     if (ext !== undefined)
       validateString(ext, 'ext');
@@ -792,6 +833,10 @@ const win32 = {
     return StringPrototypeSlice(path, start, end);
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   extname(path) {
     validateString(path, 'path');
     let start = 0;
@@ -858,6 +903,16 @@ const win32 = {
 
   format: FunctionPrototypeBind(_format, null, '\\'),
 
+  /**
+   * @param {string} path
+   * @returns {{
+   *  dir: string;
+   *  root: string;
+   *  base: string;
+   *  name: string;
+   *  ext: string;
+   *  }}
+   */
   parse(path) {
     validateString(path, 'path');
 
@@ -1032,7 +1087,11 @@ const posixCwd = (() => {
 })();
 
 const posix = {
-  // path.resolve([from ...], to)
+  /**
+   * path.resolve([from ...], to)
+   * @param {...string} args
+   * @returns {string}
+   */
   resolve(...args) {
     let resolvedPath = '';
     let resolvedAbsolute = false;
@@ -1065,6 +1124,10 @@ const posix = {
     return resolvedPath.length > 0 ? resolvedPath : '.';
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   normalize(path) {
     validateString(path, 'path');
 
@@ -1090,12 +1153,20 @@ const posix = {
     return isAbsolute ? `/${path}` : path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {boolean}
+   */
   isAbsolute(path) {
     validateString(path, 'path');
     return path.length > 0 &&
            StringPrototypeCharCodeAt(path, 0) === CHAR_FORWARD_SLASH;
   },
 
+  /**
+   * @param {...string} args
+   * @returns {string}
+   */
   join(...args) {
     if (args.length === 0)
       return '.';
@@ -1115,6 +1186,11 @@ const posix = {
     return posix.normalize(joined);
   },
 
+  /**
+   * @param {string} from
+   * @param {string} to
+   * @returns {string}
+   */
   relative(from, to) {
     validateString(from, 'from');
     validateString(to, 'to');
@@ -1196,6 +1272,10 @@ const posix = {
     return path;
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   dirname(path) {
     validateString(path, 'path');
     if (path.length === 0)
@@ -1222,6 +1302,11 @@ const posix = {
     return StringPrototypeSlice(path, 0, end);
   },
 
+  /**
+   * @param {string} path
+   * @param {string} [ext]
+   * @returns {string}
+   */
   basename(path, ext) {
     if (ext !== undefined)
       validateString(ext, 'ext');
@@ -1297,6 +1382,10 @@ const posix = {
     return StringPrototypeSlice(path, start, end);
   },
 
+  /**
+   * @param {string} path
+   * @returns {string}
+   */
   extname(path) {
     validateString(path, 'path');
     let startDot = -1;
@@ -1351,6 +1440,16 @@ const posix = {
 
   format: FunctionPrototypeBind(_format, null, '/'),
 
+  /**
+   * @param {string} path
+   * @returns {{
+   *   dir: string;
+   *   root: string;
+   *   base: string;
+   *   name: string;
+   *   ext: string;
+   *   }}
+   */
   parse(path) {
     validateString(path, 'path');