From ce890f2ae7e8b557211e8f529180d30dc44ea7b5 Mon Sep 17 00:00:00 2001 From: Mo Date: Sat, 21 Nov 2020 20:23:24 +0200 Subject: [PATCH] docs(std/path): add missing JSDoc (#8282) --- std/path/posix.ts | 63 ++++++++++++++++++++++++++++++++++++++--------- std/path/win32.ts | 62 ++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 107 insertions(+), 18 deletions(-) diff --git a/std/path/posix.ts b/std/path/posix.ts index e5cbbd6c18..eb88be079e 100644 --- a/std/path/posix.ts +++ b/std/path/posix.ts @@ -16,7 +16,10 @@ export const sep = "/"; export const delimiter = ":"; // path.resolve([from ...], to) -/** resolves `pathSegments` into an absolute path. */ +/** + * Resolves `pathSegments` into an absolute path. + * @param pathSegments an array of path segments + */ export function resolve(...pathSegments: string[]): string { let resolvedPath = ""; let resolvedAbsolute = false; @@ -61,7 +64,10 @@ export function resolve(...pathSegments: string[]): string { else return "."; } -/** Notmalize the `path`, resolving `'..'` and `'.'` segments. */ +/** + * Normalize the `path`, resolving `'..'` and `'.'` segments. + * @param path to be normalized + */ export function normalize(path: string): string { assertPath(path); @@ -81,12 +87,19 @@ export function normalize(path: string): string { return path; } +/** + * Verifies whether provided path is absolute + * @param path to be verified as absolute + */ export function isAbsolute(path: string): boolean { assertPath(path); return path.length > 0 && path.charCodeAt(0) === CHAR_FORWARD_SLASH; } -/** Join all given a sequence of `paths`,then normalizes the resulting path. */ +/** + * Join all given a sequence of `paths`,then normalizes the resulting path. + * @param paths to be joined and normalized + */ export function join(...paths: string[]): string { if (paths.length === 0) return "."; let joined: string | undefined; @@ -102,7 +115,11 @@ export function join(...paths: string[]): string { return normalize(joined); } -/** Return the relative path from `from` to `to` based on current working directory. */ +/** + * Return the relative path from `from` to `to` based on current working directory. + * @param from path in current working directory + * @param to path in current working directory + */ export function relative(from: string, to: string): string { assertPath(from); assertPath(to); @@ -185,12 +202,19 @@ export function relative(from: string, to: string): string { } } +/** + * Resolves path to a namespace path + * @param path to resolve to namespace + */ export function toNamespacedPath(path: string): string { // Non-op on posix systems return path; } -/** Return the directory name of a `path`. */ +/** + * Return the directory name of a `path`. + * @param path to determine name for + */ export function dirname(path: string): string { assertPath(path); if (path.length === 0) return "."; @@ -214,7 +238,11 @@ export function dirname(path: string): string { return path.slice(0, end); } -/** Return the last portion of a `path`. Trailing directory separators are ignored. */ +/** + * Return the last portion of a `path`. Trailing directory separators are ignored. + * @param path to process + * @param ext of path directory + */ export function basename(path: string, ext = ""): string { if (ext !== undefined && typeof ext !== "string") { throw new TypeError('"ext" argument must be a string'); @@ -289,7 +317,10 @@ export function basename(path: string, ext = ""): string { } } -/** Return the extention of the `path`. */ +/** + * Return the extension of the `path`. + * @param path with extension + */ export function extname(path: string): string { assertPath(path); let startDot = -1; @@ -340,7 +371,10 @@ export function extname(path: string): string { return path.slice(startDot, end); } -/** Generate a path from `FormatInputPathObject` object. */ +/** + * Generate a path from `FormatInputPathObject` object. + * @param pathObject with path + */ export function format(pathObject: FormatInputPathObject): string { if (pathObject === null || typeof pathObject !== "object") { throw new TypeError( @@ -350,7 +384,10 @@ export function format(pathObject: FormatInputPathObject): string { return _format("/", pathObject); } -/** Return a `ParsedPath` object of the `path`. */ +/** + * Return a `ParsedPath` object of the `path`. + * @param path to process + */ export function parse(path: string): ParsedPath { assertPath(path); @@ -435,9 +472,11 @@ export function parse(path: string): ParsedPath { return ret; } -/** Converts a file URL to a path string. +/** + * Converts a file URL to a path string. * * fromFileUrl("file:///home/foo"); // "/home/foo" + * @param url of a file URL */ export function fromFileUrl(url: string | URL): string { url = url instanceof URL ? url : new URL(url); @@ -449,9 +488,11 @@ export function fromFileUrl(url: string | URL): string { ); } -/** Converts a path string to a file URL. +/** + * Converts a path string to a file URL. * * toFileUrl("/home/foo"); // new URL("file:///home/foo") + * @param path to convert to file URL */ export function toFileUrl(path: string): URL { if (!isAbsolute(path)) { diff --git a/std/path/win32.ts b/std/path/win32.ts index 6daff65c87..f974511e2c 100644 --- a/std/path/win32.ts +++ b/std/path/win32.ts @@ -1,7 +1,6 @@ // Copyright the Browserify authors. MIT License. // Ported from https://github.com/browserify/path-browserify/ /** This module is browser compatible. */ - import type { FormatInputPathObject, ParsedPath } from "./_interface.ts"; import { CHAR_BACKWARD_SLASH, @@ -22,6 +21,10 @@ import { assert } from "../_util/assert.ts"; export const sep = "\\"; export const delimiter = ";"; +/** + * Resolves path segments into a `path` + * @param pathSegments to process to path + */ export function resolve(...pathSegments: string[]): string { let resolvedDevice = ""; let resolvedTail = ""; @@ -173,6 +176,10 @@ export function resolve(...pathSegments: string[]): string { return resolvedDevice + (resolvedAbsolute ? "\\" : "") + resolvedTail || "."; } +/** + * Normalizes a `path` + * @param path to normalize + */ export function normalize(path: string): string { assertPath(path); const len = path.length; @@ -287,6 +294,10 @@ export function normalize(path: string): string { } } +/** + * Verifies whether path is absolute + * @param path to verify + */ export function isAbsolute(path: string): boolean { assertPath(path); const len = path.length; @@ -305,6 +316,10 @@ export function isAbsolute(path: string): boolean { return false; } +/** + * Join all given a sequence of `paths`,then normalizes the resulting path. + * @param paths to be joined and normalized + */ export function join(...paths: string[]): string { const pathsCount = paths.length; if (pathsCount === 0) return "."; @@ -367,10 +382,14 @@ export function join(...paths: string[]): string { return 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 instance: + * from = 'C:\\orandea\\test\\aaa' + * to = 'C:\\orandea\\impl\\bbb' + * The output of the function should be: '..\\..\\impl\\bbb' + * @param from relative path + * @param to relative path + */ export function relative(from: string, to: string): string { assertPath(from); assertPath(to); @@ -475,6 +494,10 @@ export function relative(from: string, to: string): string { } } +/** + * Resolves path to a namespace path + * @param path to resolve to namespace + */ export function toNamespacedPath(path: string): string { // Note: this will *probably* throw somewhere. if (typeof path !== "string") return path; @@ -509,6 +532,10 @@ export function toNamespacedPath(path: string): string { return path; } +/** + * Return the directory name of a `path`. + * @param path to determine name for + */ export function dirname(path: string): string { assertPath(path); const len = path.length; @@ -597,6 +624,11 @@ export function dirname(path: string): string { return path.slice(0, end); } +/** + * Return the last portion of a `path`. Trailing directory separators are ignored. + * @param path to process + * @param ext of path directory + */ export function basename(path: string, ext = ""): string { if (ext !== undefined && typeof ext !== "string") { throw new TypeError('"ext" argument must be a string'); @@ -682,6 +714,10 @@ export function basename(path: string, ext = ""): string { } } +/** + * Return the extension of the `path`. + * @param path with extension + */ export function extname(path: string): string { assertPath(path); let start = 0; @@ -746,6 +782,10 @@ export function extname(path: string): string { return path.slice(startDot, end); } +/** + * Generate a path from `FormatInputPathObject` object. + * @param pathObject with path + */ export function format(pathObject: FormatInputPathObject): string { if (pathObject === null || typeof pathObject !== "object") { throw new TypeError( @@ -755,6 +795,10 @@ export function format(pathObject: FormatInputPathObject): string { return _format("\\", pathObject); } +/** + * Return a `ParsedPath` object of the `path`. + * @param path to process + */ export function parse(path: string): ParsedPath { assertPath(path); @@ -904,11 +948,13 @@ export function parse(path: string): ParsedPath { return ret; } -/** Converts a file URL to a path string. +/** + * Converts a file URL to a path string. * * fromFileUrl("file:///home/foo"); // "\\home\\foo" * fromFileUrl("file:///C:/Users/foo"); // "C:\\Users\\foo" * fromFileUrl("file://localhost/home/foo"); // "\\\\localhost\\home\\foo" + * @param url of a file URL */ export function fromFileUrl(url: string | URL): string { url = url instanceof URL ? url : new URL(url); @@ -927,11 +973,13 @@ export function fromFileUrl(url: string | URL): string { return path; } -/** Converts a path string to a file URL. +/** + * Converts a path string to a file URL. * * toFileUrl("\\home\\foo"); // new URL("file:///home/foo") * toFileUrl("C:\\Users\\foo"); // new URL("file:///C:/Users/foo") * toFileUrl("\\\\localhost\\home\\foo"); // new URL("file://localhost/home/foo") + * @param path to convert to file URL */ export function toFileUrl(path: string): URL { if (!isAbsolute(path)) {