docs(path): improve API docs

_tools/check_docs.ts

@@ -45,6 +45,7 @@ const ENTRY_POINTS = [
   "../internal/mod.ts",
   "../jsonc/mod.ts",
   "../media_types/mod.ts",
+  "../path/mod.ts",
   "../semver/mod.ts",
   "../streams/mod.ts",
   "../text/mod.ts",

path/_interface.ts

@@ -39,4 +39,7 @@ export interface ParsedPath {
   name: string;
 }
 
+/**
+ * A parsed path object to be consumed by `path.format()`.
+ */
 export type FormatInputPathObject = Partial<ParsedPath>;

path/_os.ts

@@ -2,6 +2,10 @@
 // This module is browser compatible.
 
 // Keep this up-to-date with Deno.build.os
+/**
+ * Operating system type, equivalent to the type of
+ * {@linkcode https://deno.land/api?s=Deno.build | Deno.build.os}.
+ */
 export type OSType =
   | "darwin"
   | "linux"

path/basename.ts

@@ -6,20 +6,27 @@ import { basename as posixBasename } from "./posix/basename.ts";
 import { basename as windowsBasename } from "./windows/basename.ts";
 
 /**
- * Return the last portion of a `path`.
- * Trailing directory separators are ignored, and optional suffix is removed.
+ * Return the last portion of a path.
  *
- * @example
+ * The trailing directory separators are ignored, and optional suffix is
+ * removed.
+ *
+ * @example Usage
  * ```ts
  * import { basename } from "@std/path/basename";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * basename("/home/user/Documents/"); // "Documents"
- * basename("C:\\user\\Documents\\image.png"); // "image.png"
- * basename("/home/user/Documents/image.png", ".png"); // "image"
+ * if (Deno.build.os === "windows") {
+ *   assertEquals(basename("C:\\user\\Documents\\image.png"), "image.png");
+ * } else {
+ *   assertEquals(basename("/home/user/Documents/image.png"), "image.png");
+ * }
  * ```
  *
- * @param path - path to extract the name from.
- * @param [suffix] - suffix to remove from extracted name.
+ * @param path Path to extract the name from.
+ * @param suffix Suffix to remove from extracted name.
+ *
+ * @returns The basename of the path.
  */
 export function basename(path: string, suffix = ""): string {
   return isWindows

path/common.ts

@@ -4,16 +4,22 @@
 import { _common } from "./_common/common.ts";
 import { SEPARATOR } from "./constants.ts";
 
-/** Determines the common path from a set of paths, using an optional separator,
+/**
+ * Determines the common path from a set of paths, using an optional separator,
  * which defaults to the OS default separator.
  *
+ * @param paths Paths to search for common path.
+ * @param sep Path separator to use.
+ * @returns The common path.
+ *
+ * @example Usage
  * ```ts
- *       import { common } from "@std/path";
- *       const p = common([
- *         "./deno/std/path/mod.ts",
- *         "./deno/std/fs/mod.ts",
- *       ]);
- *       console.log(p); // "./deno/std/"
+ * import { common } from "@std/path";
+ *
+ * common([
+ *   "./deno/std/path/mod.ts",
+ *   "./deno/std/fs/mod.ts"
+ * ]); // "./deno/std/"
  * ```
  */
 export function common(

path/constants.ts

@@ -2,6 +2,17 @@
 // This module is browser compatible.
 import { isWindows } from "./_os.ts";
 
+/**
+ * The character used to separate entries in the PATH environment variable.
+ * On Windows, this is `;`. On all other platforms, this is `:`.
+ */
 export const DELIMITER = isWindows ? ";" as const : ":" as const;
+/**
+ * The character used to separate components of a file path.
+ * On Windows, this is `\`. On all other platforms, this is `/`.
+ */
 export const SEPARATOR = isWindows ? "\\" as const : "/" as const;
+/**
+ * A regular expression that matches one or more path separators.
+ */
 export const SEPARATOR_PATTERN = isWindows ? /[\\/]+/ : /\/+/;

path/dirname.ts

@@ -6,8 +6,20 @@ import { dirname as posixDirname } from "./posix/dirname.ts";
 import { dirname as windowsDirname } from "./windows/dirname.ts";
 
 /**
- * Return the directory path of a `path`.
- * @param path - path to extract the directory from.
+ * Return the directory path of a pauth.
+ *
+ * @param path Path to extract the directory from.
+ *
+ * @returns The directory path.
+ *
+ * @example Usage
+ * ```ts
+ * import { dirname } from "@std/path/dirname";
+ *
+ * dirname("/home/user/Documents/image.png"); // "/home/user/Documents"
+ * dirname("C:\\user\\Documents\\image.png"); // "C:\\user\\Documents"
+ * dirname("image.png"); // "."
+ * ```
  */
 export function dirname(path: string): string {
   return isWindows ? windowsDirname(path) : posixDirname(path);

path/extname.ts

@@ -5,9 +5,19 @@ import { isWindows } from "./_os.ts";
 import { extname as posixExtname } from "./posix/extname.ts";
 import { extname as windowsExtname } from "./windows/extname.ts";
 /**
- * Return the extension of the `path` with leading period.
- * @param path with extension
- * @returns extension (ex. for `file.ts` returns `.ts`)
+ * Return the extension of the path with leading period (".").
+ *
+ * @param path Path with extension.
+ *
+ * @returns The file extension. E.g. returns `.ts` for `file.ts`.
+ *
+ * @example Usage
+ * ```ts
+ * import { extname } from "@std/path/extname";
+ *
+ * extname("/home/user/Documents/image.png"); // ".png"
+ * extname("C:\\user\\Documents\\image.png"); // ".png"
+ * ```
  */
 export function extname(path: string): string {
   return isWindows ? windowsExtname(path) : posixExtname(path);

path/format.ts

@@ -7,10 +7,19 @@ import { format as windowsFormat } from "./windows/format.ts";
 import type { FormatInputPathObject } from "./_interface.ts";
 
 /**
- * Generate a path from `FormatInputPathObject` object. It does the opposite
- * of `parse`.
+ * Generate a path from a {@linkcode FormatInputPathObject} object. It does the
+ * opposite of {@linkcode https://jsr.io/@std/path/doc/~/parse | parse()}.
  *
- * @param pathObject with path
+ * @param pathObject Object with path components.
+ * @returns The formatted path.
+ *
+ * @example Usage
+ * ```ts
+ * import { format } from "@std/path/format";
+ *
+ * format({ dir: "/path/to/dir", base: "script.ts" }); // "/path/to/dir/script.ts"
+ * format({ root: "/", name: "script", ext: ".ts" }); // "/script.ts"
+ * ```
  */
 export function format(pathObject: FormatInputPathObject): string {
   return isWindows ? windowsFormat(pathObject) : posixFormat(pathObject);

path/from_file_url.ts

@@ -8,6 +8,7 @@ import { fromFileUrl as windowsFromFileUrl } from "./windows/from_file_url.ts";
 /**
  * Converts a file URL to a path string.
  *
+ * @example Usage
  * ```ts
  * import { fromFileUrl } from "@std/path/from-file-url";
  *
@@ -19,7 +20,9 @@ import { fromFileUrl as windowsFromFileUrl } from "./windows/from_file_url.ts";
  * fromFileUrl("file:///C:/Users/foo"); // "C:\\Users\\foo"
  * fromFileUrl("file://localhost/home/foo"); // "\\\\localhost\\home\\foo"
  * ```
- * @param url of a file URL
+ * @param url The file URL to convert to a path.
+ *
+ * @returns The path string.
  */
 export function fromFileUrl(url: string | URL): string {
   return isWindows ? windowsFromFileUrl(url) : posixFromFileUrl(url);

path/glob_to_regexp.ts

@@ -9,13 +9,20 @@ import {
   globToRegExp as windowsGlobToRegExp,
 } from "./windows/glob_to_regexp.ts";
 
-export type { GlobOptions };
+export type { GlobOptions, OSType };
 
+/** Options for {@linkcode globToRegExp}. */
 export type GlobToRegExpOptions = GlobOptions & {
+  /**
+   * The operating system to interpret paths as.
+   *
+   * If unset, it defaults to the current operating system.
+   */
   os?: OSType;
 };
 
-/** Convert a glob string to a regular expression.
+/**
+ * Converts a glob string to a regular expression.
  *
  * Tries to match bash glob expansion as closely as possible.
  *
@@ -69,7 +76,19 @@ export type GlobToRegExpOptions = GlobOptions & {
  *   look-ahead followed by a wildcard. This means that `!(foo).js` will wrongly
  *   fail to match `foobar.js`, even though `foobar` is not `foo`. Effectively,
  *   `!(foo|bar)` is treated like `!(@(foo|bar)*)`. This will work correctly if
- *   the group occurs not nested at the end of the segment. */
+ *   the group occurs not nested at the end of the segment.
+ *
+ * @param glob Glob string to convert.
+ * @param options Conversion options.
+ * @returns The regular expression equivalent to the glob.
+ *
+ * @example Usage
+ * ```ts
+ * import { globToRegExp } from "@std/path/glob-to-regexp";
+ *
+ * globToRegExp("*.js"); // /^[^/]*\.js\/*$/;
+ * ```
+ */
 export function globToRegExp(
   glob: string,
   options: GlobToRegExpOptions = {},

path/is_absolute.ts

@@ -6,8 +6,24 @@ import { isAbsolute as posixIsAbsolute } from "./posix/is_absolute.ts";
 import { isAbsolute as windowsIsAbsolute } from "./windows/is_absolute.ts";
 
 /**
- * Verifies whether provided path is absolute
- * @param path to be verified as absolute
+ * Verifies whether provided path is absolute.
+ *
+ * @param path Path to be verified as absolute.
+ *
+ * @returns `true` if path is absolute, `false` otherwise
+ *
+ * @example Usage
+ * ```ts
+ * import { isAbsolute } from "@std/path/is-absolute";
+ *
+ * // posix
+ * isAbsolute("/home/foo"); // true
+ * isAbsolute("home/foo"); // false
+ *
+ * // win32
+ * isAbsolute("C:\\home\\foo"); // true
+ * isAbsolute("home\\foo"); // false
+ * ```
  */
 export function isAbsolute(path: string): boolean {
   return isWindows ? windowsIsAbsolute(path) : posixIsAbsolute(path);

path/is_glob.ts

@@ -1,7 +1,22 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Test whether the given string is a glob */
+/**
+ * Test whether the given string is a glob.
+ *
+ * @param str String to test.
+ *
+ * @returns `true` if the given string is a glob, otherwise `false`
+ *
+ * @example Usage
+ * ```ts
+ * import { isGlob } from "@std/path/is-glob";
+ * import { assert } from "@std/assert/assert";
+ *
+ * assert(!isGlob("foo/bar/../baz"));
+ * assert(isGlob("foo/*ar/../baz"));
+ * ```
+ */
 export function isGlob(str: string): boolean {
   const chars: Record<string, string> = { "{": "}", "(": ")", "[": "]" };
   const regex =

path/join.ts

@@ -6,8 +6,22 @@ import { join as posixJoin } from "./posix/join.ts";
 import { join as windowsJoin } from "./windows/join.ts";
 
 /**
- * Join all given a sequence of `paths`,then normalizes the resulting path.
- * @param paths to be joined and normalized
+ * Join all given a sequence of paths, then normalizes the resulting path.
+ *
+ * @param paths Paths to be joined and normalized.
+ *
+ * @returns The joined and normalized path.
+ *
+ * @example Usage
+ * ```ts
+ * import { join } from "@std/path/join";
+ *
+ * // posix
+ * join("/foo", "bar", "baz/quux", "garply", ".."); // "/foo/bar/baz/quux"
+ *
+ * // win32
+ * join("C:\\foo", "bar", "baz\\quux", "garply", ".."); // "C:\\foo\\bar\\baz\\quux"
+ * ```
  */
 export function join(...paths: string[]): string {
   return isWindows ? windowsJoin(...paths) : posixJoin(...paths);

path/join_globs.ts

@@ -8,7 +8,25 @@ import { joinGlobs as windowsJoinGlobs } from "./windows/join_globs.ts";
 
 export type { GlobOptions };
 
-/** Like join(), but doesn't collapse "**\/.." when `globstar` is true. */
+/**
+ * Joins a sequence of globs, then normalizes the resulting glob.
+ *
+ * Behaves like {@linkcode https://jsr.io/@std/path/doc/~/join | join()}, but
+ * doesn't collapse `**\/..` when `globstar` is true.
+ *
+ * @param globs Globs to be joined and normalized.
+ * @param options Glob options.
+ *
+ * @returns The joined and normalized glob string.
+ *
+ * @example Usage
+ * ```ts
+ * import { joinGlobs } from "@std/path/join-globs";
+ *
+ * joinGlobs(["foo", "bar", "..", "baz"]); // "foo/baz"
+ * joinGlobs(["foo", "**\/..", "bar", "..", "baz"], { globstar: true }); // "foo/**\/../baz"
+ * ```
+ */
 export function joinGlobs(
   globs: string[],
   options: GlobOptions = {},

path/mod.ts

@@ -38,12 +38,16 @@ import * as _windows from "./windows/mod.ts";
 import * as _posix from "./posix/mod.ts";
 
 /**
+ * Module for working with Windows file paths.
+ *
  * @deprecated This will be removed in 1.0.0. Import from
  * {@link https://jsr.io/@std/path/doc/windows/~ | @std/path/windows} instead.
  */
 export const win32: typeof _windows = _windows;
 
 /**
+ * Module for working with POSIX file paths.
+ *
  * @deprecated This will be removed in 1.0.0. Import from
  * {@link https://jsr.io/@std/path/doc/posix/~ | @std/path/posix} instead.
  */

path/normalize.ts

@@ -5,10 +5,26 @@ import { isWindows } from "./_os.ts";
 import { normalize as posixNormalize } from "./posix/normalize.ts";
 import { normalize as windowsNormalize } from "./windows/normalize.ts";
 /**
- * Normalize the `path`, resolving `'..'` and `'.'` segments.
- * Note that resolving these segments does not necessarily mean that all will be eliminated.
- * A `'..'` at the top-level will be preserved, and an empty path is canonically `'.'`.
- * @param path to be normalized
+ * Normalize the pat`, resolving `'..'` and `'.'` segments.
+ *
+ * Note: Resolving these segments does not necessarily mean that all will be
+ * eliminated. A `'..'` at the top-level will be preserved, and an empty path is
+ * canonically `'.'`.
+ *
+ * @param path Path to be normalized
+ *
+ * @returns The normalized path.
+ *
+ * @example Usage
+ * ```ts
+ * import { normalize } from "@std/path/normalize";
+ *
+ * // posix
+ * normalize("/foo/bar/./baz/.././quux"); // "/foo/bar/quux"
+ *
+ * // win32
+ * normalize("C:\\foo\\bar\\.\\baz\\..\\.\\quux"); // "C:\\foo\\bar\\quux"
+ * ```
  */
 export function normalize(path: string): string {
   return isWindows ? windowsNormalize(path) : posixNormalize(path);