From 351b81db138260a35ce640d0ca8f136329617093 Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 13 Apr 2024 10:01:56 -0400 Subject: [PATCH 1/2] docs: Update JSDoc and fix a few typos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add a “-” to separate the parameter name from its description. - Fixed a few `@param` names that differed from their actual parameter name in code. - Marked `[optional]` params and their `[default=values]`. --- src/TemplatePath.js | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/src/TemplatePath.js b/src/TemplatePath.js index efbf464..abb2856 100644 --- a/src/TemplatePath.js +++ b/src/TemplatePath.js @@ -15,7 +15,7 @@ TemplatePath.getWorkingDir = function () { * Returns the directory portion of a path. * Works for directory and file paths and paths ending in a glob pattern. * - * @param {String} path A path + * @param {String} path - A path * @returns {String} the directory portion of a path. */ TemplatePath.getDir = function (path) { @@ -34,8 +34,8 @@ TemplatePath.getDir = function (path) { * * [1]: https://nodejs.org/api/path.html#path_path_parse_path * - * @param {String} path A path * @returns {String} the directory portion of a path. + * @param {String} filePath - A path */ TemplatePath.getDirFromFilePath = function (filePath) { return path.parse(filePath).dir || "."; @@ -48,7 +48,7 @@ TemplatePath.getDirFromFilePath = function (filePath) { * * [1]: https://nodejs.org/api/path.html#path_path_parse_path * - * @param {String} path A path + * @param {String} path - A path * @returns {String} the last path segment in a path */ TemplatePath.getLastPathSegment = function (path) { @@ -63,7 +63,7 @@ TemplatePath.getLastPathSegment = function (path) { }; /** - * @param {String} path A path + * @param {String} path - A path * @returns {String[]} an array of paths pointing to each path segment of the * provided `path`. */ @@ -89,7 +89,7 @@ TemplatePath.getAllDirs = function (path) { * * [1]: https://nodejs.org/api/path.html#path_path_normalize_path * - * @param {String} thePath The path that should be normalized. + * @param {String} thePath - The path that should be normalized. * @returns {String} the normalized path. */ TemplatePath.normalize = function (thePath) { @@ -104,7 +104,7 @@ TemplatePath.normalize = function (thePath) { * [1]: https://nodejs.org/api/path.html#path_path_join_paths * [2]: https://www.npmjs.com/package/normalize-path * - * @param {String[]} paths An arbitrary amount of path segments. + * @param {...String} paths - An arbitrary amount of path segments. * @returns {String} the normalized and joined path. */ TemplatePath.join = function (...paths) { @@ -116,7 +116,7 @@ TemplatePath.join = function (...paths) { * Maintains a single trailing slash if the last URL path argument * had at least one. * - * @param {String[]} urlPaths + * @param {...String} urlPaths * @returns {String} a normalized URL path described by the given URL path segments. */ TemplatePath.normalizeUrlPath = function (...urlPaths) { @@ -128,7 +128,7 @@ TemplatePath.normalizeUrlPath = function (...urlPaths) { * Joins the given path segments. Since the first path is absolute, * the resulting path will be absolute as well. * - * @param {String[]} paths + * @param {...String} paths * @returns {String} the absolute path described by the given path segments. */ TemplatePath.absolutePath = function (...paths) { @@ -180,7 +180,7 @@ TemplatePath.addLeadingDotSlashArray = function (paths) { /** * Adds a leading dot-slash segment to `path`. * - * @param {String} path + * @param {String} pathArg * @returns {String} */ TemplatePath.addLeadingDotSlash = function (pathArg) { @@ -212,8 +212,8 @@ TemplatePath.stripLeadingDotSlash = function (path) { /** * Determines whether a path starts with a given sub path. * - * @param {String} path A path - * @param {String} subPath A path + * @param {String} path - A path + * @param {String} subPath - A path * @returns {Boolean} whether `path` starts with `subPath`. */ TemplatePath.startsWithSubPath = function (path, subPath) { @@ -227,8 +227,8 @@ TemplatePath.startsWithSubPath = function (path, subPath) { * Removes the `subPath` at the start of `path` if present * and returns the remainding path. * - * @param {String} path A path - * @param {String} subPath A path + * @param {String} path - A path + * @param {String} subPath - A path * @returns {String} the `path` without `subPath` at the start of it. */ TemplatePath.stripLeadingSubPath = function (path, subPath) { @@ -243,7 +243,7 @@ TemplatePath.stripLeadingSubPath = function (path, subPath) { }; /** - * @param {String} path A path + * @param {String} path - A path * @returns {Boolean} whether `path` points to an existing directory. */ TemplatePath.isDirectorySync = function (path) { @@ -251,7 +251,7 @@ TemplatePath.isDirectorySync = function (path) { }; /** - * @param {String} path A path + * @param {String} path - A path * @returns {Boolean} whether `path` points to an existing directory. */ TemplatePath.isDirectory = async function (path) { @@ -325,7 +325,7 @@ TemplatePath.getExtension = function (thePath) { * Removes the extension from a path. * * @param {String} path - * @param {String} extension + * @param {String} [extension] * @returns {String} */ TemplatePath.removeExtension = function (path, extension = undefined) { @@ -347,6 +347,7 @@ TemplatePath.removeExtension = function (path, extension = undefined) { * e.g. `./my/dir/` stays `./my/dir/` on *nix and becomes `.\\my\\dir\\` on Windows * * @param {String} filePath + * @param {String} [sep="/"] * @returns {String} a file path with the correct local directory separator. */ TemplatePath.normalizeOperatingSystemFilePath = function (filePath, sep = "/") { @@ -359,6 +360,7 @@ TemplatePath.normalizeOperatingSystemFilePath = function (filePath, sep = "/") { * e.g. `./my/dir/` stays `./my/dir/` on *nix and becomes `.\\my\\dir\\` on Windows * * @param {String} filePath + * @param {String} [sep="/"] * @returns {String} a file path with the correct local directory separator. */ TemplatePath.standardizeFilePath = function (filePath, sep = "/") { From 1debb0c4c1d0fc06cad09de13fa09dffa9295a9f Mon Sep 17 00:00:00 2001 From: Zearin Date: Sat, 13 Apr 2024 10:05:23 -0400 Subject: [PATCH 2/2] fix: Replace deprecated `substr()` with `substring()` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [`String.prototype.substr()`](substr) is deprecated. The meaning of the _second_ parameter to both functions is different (length vs. stop-index)—_but_, since calls to `substr()` were made with only 1 argument, the difference does not matter. [substr]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr --- src/TemplatePath.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/TemplatePath.js b/src/TemplatePath.js index abb2856..0420973 100644 --- a/src/TemplatePath.js +++ b/src/TemplatePath.js @@ -59,7 +59,7 @@ TemplatePath.getLastPathSegment = function (path) { // Trim a trailing slash if there is one path = path.replace(/\/$/, ""); - return path.substr(path.lastIndexOf("/") + 1); + return path.substring(path.lastIndexOf("/") + 1); }; /** @@ -236,7 +236,7 @@ TemplatePath.stripLeadingSubPath = function (path, subPath) { subPath = TemplatePath.normalize(subPath); if (subPath !== "." && path.startsWith(subPath)) { - return path.substr(subPath.length + 1); + return path.substring(subPath.length + 1); } return path;