foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-22 15:06:54 -05:00
Code Issues Packages 1 Wiki Activity

docs(std/path): add missing JSDoc (#8282)

Browse source
This commit is contained in:
Mo 2020-11-21 20:23:24 +02:00 committed by GitHub
parent 27dd786016
commit ce890f2ae7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 107 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
std/path/posix.ts
View file

@ -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)) {

62
std/path/win32.ts
View file

@ -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)) {