docs(url): polish documentation (#4601)

2024-11-22 04:59:05 +00:00 · 2024-04-17 14:49:49 +10:00 · 2024-04-17 14:49:49 +10:00 · d87ef8078f
commit d87ef8078f
parent 31018f12b7
6 changed files with 157 additions and 59 deletions
--- a/url/basename.ts
+++ b/url/basename.ts
@ -5,31 +5,42 @@ import { basename as posixBasename } from "../path/posix/basename.ts";
 import { strip } from "./_strip.ts";

 /**
- * Return the last portion of a `URL`, or the host name if there is no path.
- * Trailing `/`s are ignored, and optional suffix is removed.
+ * Returns the base name of a URL or URL string, optionally removing a suffix.
 *
- * @example
+ * Trailing `/`s are ignored. If no path is present, the host name is returned.
+ *
+ * @param url The URL from which to extract the base name.
+ * @param suffix An optional suffix to remove from the base name.
+ * @returns The base name of the URL.
+ *
+ * @example Basic usage
 * ```ts
 * import { basename } from "https://deno.land/std@$STD_VERSION/url/basename.ts";
 *
- * // basename accepts a string or URL
- * console.log(basename("https://deno.land/std/assert/mod.ts"));  // "mod.ts"
- * console.log(basename(new URL("https://deno.land/std/assert/mod.ts"))); // "mod.ts"
+ * basename("https://deno.land/std/assert/mod.ts"); // "mod.ts"
 *
- * // basename accepts an optional suffix to remove
- * console.log(basename(new URL("https://deno.land/std/assert/mod.ts"), ".ts")); // "mod"
+ * basename(new URL("https://deno.land/std/assert/mod.ts")); // "mod.ts"
 *
- * // basename does not include query parameters or hash fragments
- * console.log(basename(new URL("https://deno.land/std/assert/mod.ts?a=b"))); // "mod.ts"
- * console.log(basename(new URL("https://deno.land/std/assert/mod.ts#header"))); // "mod.ts"
+ * basename("https://deno.land/std/assert/mod.ts?a=b"); // "mod.ts"
 *
- * // If no path is present, the host name is returned
- * console.log(basename(new URL("https://deno.land/"))); // "deno.land"
+ * basename("https://deno.land/std/assert/mod.ts#header"); // "mod.ts"
+ *
+ * basename("https://deno.land/"); // "deno.land"
 * ```
 *
- * @param url - url to extract the final path segment from.
- * @param suffix - optional suffix to remove from extracted name.
- * @returns the last portion of the URL `path`, or the URL origin if there is no path.
+ * @example Removing a suffix
+ * ```ts
+ * import { basename } from "https://deno.land/std@$STD_VERSION/url/basename.ts";
+ *
+ * basename("https://deno.land/std/assert/mod.ts", ".ts"); // "mod"
+ *
+ * basename(new URL("https://deno.land/std/assert/mod.ts"), ".ts"); // "mod"
+ *
+ * basename("https://deno.land/std/assert/mod.ts?a=b", ".ts"); // "mod"
+ *
+ * basename("https://deno.land/std/assert/mod.ts#header", ".ts"); // "mod.ts"
+ * ```
+ * Defining a suffix will remove it from the base name.
 */
 export function basename(url: string | URL, suffix?: string): string {
  url = new URL(url);
--- a/url/dirname.ts
+++ b/url/dirname.ts
@ -5,24 +5,27 @@ import { dirname as posixDirname } from "../path/posix/dirname.ts";
 import { strip } from "./_strip.ts";

 /**
- * Return the directory path of a `URL`.  A directory path is the portion of a
- * `URL` up to but excluding the final path segment.  The final path segment,
- * along with any query or hash values are removed. If there is no path segment
- * then the URL origin is returned. Example, for the URL
- * `https://deno.land/std/path/mod.ts`, the directory path is
- * `https://deno.land/std/path`.
+ * Returns the directory path of a URL or URL string.
 *
- * @example
+ * The directory path is the portion of a URL up to but excluding the final path
+ * segment.
+ *
+ * The final path segment, along with any query or hash values are
+ * removed. If there is no path segment then the URL origin is returned.
+ *
+ * @param url URL to extract the directory from.
+ * @returns The directory path of the URL.
+ *
+ * @example Basic usage
 * ```ts
 * import { dirname } from "https://deno.land/std@$STD_VERSION/url/dirname.ts";
 *
- * console.log(dirname("https://deno.land/std/path/mod.ts?a=b").href); // "https://deno.land/std/path"
- * console.log(dirname("https://deno.land/").href); // "https://deno.land"
- * ```
+ * dirname("https://deno.land/std/path/mod.ts?a=b").href; // "https://deno.land/std/path"
 *
- * @param url - url to extract the directory from.
- * @returns a new URL containing the directory path of the URL.
+ * dirname("https://deno.land/").href; // "https://deno.land"
+ * ```
 */
+
 export function dirname(url: string | URL): URL {
  url = new URL(url);
  strip(url);
--- a/url/extname.ts
+++ b/url/extname.ts
@ -5,22 +5,26 @@ import { extname as posixExtname } from "../path/posix/extname.ts";
 import { strip } from "./_strip.ts";

 /**
- * Return the extension of the `URL` with leading period. The extension is
- * sourced from the path portion of the `URL`.  If there is no extension,
- * an empty string is returned.
+ * Returns the file extension of a given URL or string with leading period.
 *
- * @example
+ * The extension is sourced from the path portion of the URL. If there is no
+ * extension, an empty string is returned.
+ *
+ * @param url The URL from which to extract the extension.
+ * @returns The extension of the URL.
+ *
+ * @example Basic usage
 * ```ts
 * import { extname } from "https://deno.land/std@$STD_VERSION/url/extname.ts";
 *
- * console.log(extname("https://deno.land/std/path/mod.ts")); // ".ts"
- * console.log(extname("https://deno.land/std/path/mod")); // ""
- * console.log(extname("https://deno.land/std/path/mod.ts?a=b")); // ".ts"
- * console.log(extname("https://deno.land/")); // ""
- * ```
+ * extname("https://deno.land/std/path/mod.ts"); // ".ts"
 *
- * @param url with extension
- * @returns extension (e.g. for url ending with `index.html` returns `.html`)
+ * extname("https://deno.land/std/path/mod"); // ""
+ *
+ * extname("https://deno.land/std/path/mod.ts?a=b"); // ".ts"
+ *
+ * extname("https://deno.land/"); // ""
+ * ```
 */
 export function extname(url: string | URL): string {
  url = new URL(url);
--- a/url/join.ts
+++ b/url/join.ts
@ -4,22 +4,23 @@
 import { join as posixJoin } from "../path/posix/join.ts";

 /**
- * Join a base `URL` and a series of `paths`, then normalizes the resulting URL.
+ * Joins a base URL or URL string, and a sequence of path segments together,
+ * then normalizes the resulting URL.
 *
- * @example
+ * @param url Base URL to be joined with the paths and normalized.
+ * @param paths Array of path segments to be joined to the base URL.
+ * @returns A complete URL containing the base URL joined with the paths.
+ *
+ * @example Basic usage
 * ```ts
 * import { join } from "https://deno.land/std@$STD_VERSION/url/join.ts";
 *
- * console.log(join("https://deno.land/", "std", "path", "mod.ts").href);
- * // Outputs: "https://deno.land/std/path/mod.ts"
+ * join("https://deno.land/", "std", "path", "mod.ts").href;
+ * // "https://deno.land/std/path/mod.ts"
 *
- * console.log(join("https://deno.land", "//std", "path/", "/mod.ts").href);
- * // Outputs: "https://deno.land/path/mod.ts"
+ * join("https://deno.land", "//std", "path/", "/mod.ts").href;
+ * // "https://deno.land/path/mod.ts"
 * ```
- *
- * @param url the base URL to be joined with the paths and normalized
- * @param paths array of path segments to be joined to the base URL
- * @returns a complete URL string containing the base URL joined with the paths
 */
 export function join(url: string | URL, ...paths: string[]): URL {
  url = new URL(url);
--- a/url/mod.ts
+++ b/url/mod.ts
@ -2,10 +2,89 @@
 // This module is browser compatible.

 /**
- * Utilities for working with URL paths.
+ * Utilities for working with
+ * {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/URL | URL}s.
 *
 * This module is browser compatible.
 *
+ * ## Get basename
+ *
+ * {@linkcode basename} returns the base name of a URL or URL string, optionally
+ * removing a suffix.
+ *
+ * ```ts
+ * import { basename } from "https://deno.land/std@$STD_VERSION/url/basename.ts";
+ *
+ * basename("https://deno.land/std/assert/mod.ts"); // "mod.ts"
+ *
+ * basename(new URL("https://deno.land/std/assert/mod.ts")); // "mod.ts"
+ *
+ * basename("https://deno.land/std/assert/mod.ts?a=b"); // "mod.ts"
+ *
+ * basename("https://deno.land/std/assert/mod.ts#header"); // "mod.ts"
+ *
+ * basename("https://deno.land/"); // "deno.land"
+ * ```
+ *
+ * ## Get directory path
+ *
+ * {@linkcode dirname} returns the directory path of a URL or URL string.
+ *
+ * ```ts
+ * import { dirname } from "https://deno.land/std@$STD_VERSION/url/dirname.ts";
+ *
+ * dirname("https://deno.land/std/path/mod.ts?a=b").href; // "https://deno.land/std/path"
+ *
+ * dirname("https://deno.land/").href; // "https://deno.land"
+ * ```
+ *
+ * ## Get file extension
+ *
+ * {@linkcode extname} returns the file extension of a given URL or string with
+ * leading period.
+ *
+ * ```ts
+ * import { extname } from "https://deno.land/std@$STD_VERSION/url/extname.ts";
+ *
+ * extname("https://deno.land/std/path/mod.ts"); // ".ts"
+ *
+ * extname("https://deno.land/std/path/mod"); // ""
+ *
+ * extname("https://deno.land/std/path/mod.ts?a=b"); // ".ts"
+ *
+ * extname("https://deno.land/"); // ""
+ * ```
+ *
+ * ## Join URL paths
+ *
+ * {@linkcode join} joins a base URL or URL string, and a sequence of path
+ * segments together, then normalizes the resulting URL.
+ *
+ * ```ts
+ * import { join } from "https://deno.land/std@$STD_VERSION/url/join.ts";
+ *
+ * join("https://deno.land/", "std", "path", "mod.ts").href;
+ * // "https://deno.land/std/path/mod.ts"
+ *
+ * join("https://deno.land", "//std", "path/", "/mod.ts").href;
+ * // "https://deno.land/path/mod.ts"
+ * ```
+ *
+ * ## Normalize URL
+ *
+ * {@linkcode normalize} normalizes the URL or URL string, resolving `..` and
+ * `.` segments. Multiple sequential `/`s are resolved into a single `/`.
+ *
+ * ```ts
+ * import { normalize } from "https://deno.land/std@$STD_VERSION/url/normalize.ts";
+ *
+ * normalize("https:///deno.land///std//assert//.//mod.ts").href;
+ * // "https://deno.land/std/path/mod.ts"
+ *
+ * normalize("https://deno.land/std/assert/../async/retry.ts").href;
+ * // "https://deno.land/std/async/retry.ts"
+ * ```
+ *
 * @module
 */

--- a/url/normalize.ts
+++ b/url/normalize.ts
@ -4,22 +4,22 @@
 import { normalize as posixNormalize } from "../path/posix/normalize.ts";

 /**
- * Normalize the `URL`, resolving `'..'` and `'.'` segments and multiple
- * `'/'`s into `'//'` after protocol and remaining into `'/'`.
+ * Normalizes the URL or URL string, resolving `..` and `.` segments. Multiple
+ * sequential `/`s are resolved into a single `/`.
+ *
+ * @param url URL to be normalized.
+ * @returns Normalized URL.
 *
 * @example
 * ```ts
 * import { normalize } from "https://deno.land/std@$STD_VERSION/url/normalize.ts";
 *
- * console.log(normalize("https:///deno.land///std//assert//.//mod.ts").href);
- * // Outputs: "https://deno.land/std/path/mod.ts"
+ * normalize("https:///deno.land///std//assert//.//mod.ts").href;
+ * // "https://deno.land/std/path/mod.ts"
 *
- * console.log(normalize("https://deno.land/std/assert/../async/retry.ts").href);
- * // Outputs: "https://deno.land/std/async/retry.ts"
+ * normalize("https://deno.land/std/assert/../async/retry.ts").href;
+ * // "https://deno.land/std/async/retry.ts"
 * ```
- *
- * @param url to be normalized
- * @returns normalized URL
 */
 export function normalize(url: string | URL): URL {
  url = new URL(url);