diff --git a/lib/path.js b/lib/path.js index 7532b795bf63f7..71788e53d3efd8 100644 --- a/lib/path.js +++ b/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');