docs(url): complete documentation (#4965)

* docs(url): complete documentation

* suggestions

_tools/check_docs.ts

@@ -56,6 +56,7 @@ const ENTRY_POINTS = [
   "../text/mod.ts",
   "../toml/mod.ts",
   "../ulid/mod.ts",
+  "../url/mod.ts",
   "../uuid/mod.ts",
   "../webgpu/mod.ts",
 ] as const;

url/basename.ts

@@ -8,6 +8,8 @@ import { strip } from "./_strip.ts";
  * Returns the base name of a URL or URL string, optionally removing a suffix.
  *
  * Trailing `/`s are ignored. If no path is present, the host name is returned.
+ * If a suffix is provided, it will be removed from the base name. URL queries
+ * and hashes are ignored.
  *
  * @param url The URL from which to extract the base name.
  * @param suffix An optional suffix to remove from the base name.
@@ -16,31 +18,28 @@ import { strip } from "./_strip.ts";
  * @example Basic usage
  * ```ts
  * import { basename } from "@std/url/basename";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * 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"
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts"), "mod.ts");
+ * assertEquals(basename(new URL("https://deno.land/std/assert/mod.ts")), "mod.ts");
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts?a=b"), "mod.ts");
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts#header"), "mod.ts");
+ * assertEquals(basename("https://deno.land/"), "deno.land");
  * ```
  *
  * @example Removing a suffix
- * ```ts
- * import { basename } from "@std/url/basename";
  *
- * basename("https://deno.land/std/assert/mod.ts", ".ts"); // "mod"
- *
- * basename(new URL("https://deno.land/std/assert/mod.ts"), ".ts"); // "mod"
+ * Defining a suffix will remove it from the base name.
  *
- * basename("https://deno.land/std/assert/mod.ts?a=b", ".ts"); // "mod"
+ * ```ts
+ * import { basename } from "@std/url/basename";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * basename("https://deno.land/std/assert/mod.ts#header", ".ts"); // "mod.ts"
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts", ".ts"), "mod");
+ * assertEquals(basename(new URL("https://deno.land/std/assert/mod.ts"), ".ts"), "mod");
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts?a=b", ".ts"), "mod");
+ * assertEquals(basename("https://deno.land/std/assert/mod.ts#header", ".ts"), "mod");
  * ```
- * Defining a suffix will remove it from the base name.
  */
 export function basename(url: string | URL, suffix?: string): string {
   url = new URL(url);

url/dirname.ts

@@ -5,24 +5,21 @@ import { dirname as posixDirname } from "@std/path/posix/dirname";
 import { strip } from "./_strip.ts";
 
 /**
- * Returns the directory path of a URL or URL string.
+ * Returns the directory path URL of a URL or URL string.
  *
  * 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.
+ * segment. URL queries and hashes are ignored.
  *
  * @param url URL to extract the directory from.
- * @returns The directory path of the URL.
+ * @returns The directory path URL of the URL.
  *
- * @example Basic usage
+ * @example Usage
  * ```ts
  * import { dirname } from "@std/url/dirname";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * dirname("https://deno.land/std/path/mod.ts?a=b").href; // "https://deno.land/std/path"
- *
- * dirname("https://deno.land/").href; // "https://deno.land"
+ * assertEquals(dirname("https://deno.land/std/path/mod.ts"), new URL("https://deno.land/std/path"));
+ * assertEquals(dirname(new URL("https://deno.land/std/path/mod.ts")), new URL("https://deno.land/std/path"));
  * ```
  */
 

url/extname.ts

@@ -8,22 +8,20 @@ import { strip } from "./_strip.ts";
  * Returns the file extension of a given URL or string with leading period.
  *
  * The extension is sourced from the path portion of the URL. If there is no
- * extension, an empty string is returned.
+ * extension, an empty string is returned. URL queries and hashes are ignored.
  *
  * @param url The URL from which to extract the extension.
  * @returns The extension of the URL.
  *
- * @example Basic usage
+ * @example Usage
  * ```ts
  * import { extname } from "@std/url/extname";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * 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/"); // ""
+ * assertEquals(extname("https://deno.land/std/path/mod.ts"), ".ts");
+ * assertEquals(extname("https://deno.land/std/path/mod"), "");
+ * assertEquals(extname("https://deno.land/std/path/mod.ts?a=b"), ".ts");
+ * assertEquals(extname("https://deno.land/"), "");
  * ```
  */
 export function extname(url: string | URL): string {

url/join.ts

@@ -11,15 +11,14 @@ import { join as posixJoin } from "@std/path/posix/join";
  * @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
+ * @example Usage
+ *
  * ```ts
  * import { join } from "@std/url/join";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * 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"
+ * assertEquals(join("https://deno.land/", "std", "path", "mod.ts").href, "https://deno.land/std/path/mod.ts");
+ * assertEquals(join("https://deno.land", "//std", "path/", "/mod.ts").href, "https://deno.land/std/path/mod.ts");
  * ```
  */
 export function join(url: string | URL, ...paths: string[]): URL {

url/mod.ts

@@ -5,82 +5,19 @@
  * Utilities for working with
  * {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/URL | URL}s.
  *
- * ## Get basename
- *
- * {@linkcode basename} returns the base name of a URL or URL string, optionally
- * removing a suffix.
- *
  * ```ts
- * import { basename } from "@std/url/basename";
- *
- * 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
+ * import { basename, join, normalize } from "@std/url";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * {@linkcode dirname} returns the directory path of a URL or URL string.
+ * const url = new URL("https:///deno.land///std//assert//.//mod.ts");
+ * const normalizedUrl = normalize(url);
  *
- * ```ts
- * import { dirname } from "@std/url/dirname";
- *
- * 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 "@std/url/extname";
- *
- * 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 "@std/url/join";
- *
- * 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 "@std/url/normalize";
+ * assertEquals(normalizedUrl.href, "https://deno.land/std/assert/mod.ts");
+ * assertEquals(basename(normalizedUrl), "mod.ts");
  *
- * normalize("https:///deno.land///std//assert//.//mod.ts").href;
- * // "https://deno.land/std/path/mod.ts"
+ * const joinedUrl = join(normalizedUrl, "..", "..", "async", "retry.ts");
  *
- * normalize("https://deno.land/std/assert/../async/retry.ts").href;
- * // "https://deno.land/std/async/retry.ts"
+ * assertEquals(joinedUrl.href, "https://deno.land/std/async/retry.ts");
  * ```
  *
  * @module

url/normalize.ts

@@ -10,15 +10,14 @@ import { normalize as posixNormalize } from "@std/path/posix/normalize";
  * @param url URL to be normalized.
  * @returns Normalized URL.
  *
- * @example
+ * @example Usage
+ *
  * ```ts
  * import { normalize } from "@std/url/normalize";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * 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"
+ * assertEquals(normalize("https:///deno.land///std//assert//.//mod.ts").href, "https://deno.land/std/assert/mod.ts");
+ * assertEquals(normalize("https://deno.land/std/assert/../async/retry.ts").href, "https://deno.land/std/async/retry.ts");
  * ```
  */
 export function normalize(url: string | URL): URL {