docs(path): re-add URL examples to @std/path/posix examples (#6105)

path/posix/basename.ts

@@ -23,6 +23,23 @@ import { isPosixPathSeparator } from "./_util.ts";
  * assertEquals(basename("/home/user/Documents/image.png", ".png"), "image");
  * ```
  *
+ * @example Working with URLs
+ *
+ * Note: This function doesn't automatically strip hash and query parts from
+ * URLs. If your URL contains a hash or query, remove them before passing the
+ * URL to the function. This can be done by passing the URL to `new URL(url)`,
+ * and setting the `hash` and `search` properties to empty strings.
+ *
+ * ```ts
+ * import { basename } from "@std/path/posix/basename";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(basename("https://deno.land/std/path/mod.ts"), "mod.ts");
+ * assertEquals(basename("https://deno.land/std/path/mod.ts", ".ts"), "mod");
+ * assertEquals(basename("https://deno.land/std/path/mod.ts?a=b"), "mod.ts?a=b");
+ * assertEquals(basename("https://deno.land/std/path/mod.ts#header"), "mod.ts#header");
+ * ```
+ *
  * Note: If you are working with file URLs,
  * use the new version of `basename` from `@std/path/posix/unstable-basename`.
  *

path/posix/dirname.ts

@@ -15,6 +15,18 @@ import { isPosixPathSeparator } from "./_util.ts";
  *
  * assertEquals(dirname("/home/user/Documents/"), "/home/user");
  * assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
+ * assertEquals(dirname("https://deno.land/std/path/mod.ts"), "https://deno.land/std/path");
+ * ```
+ *
+ * @example Working with URLs
+ *
+ * ```ts
+ * import { dirname } from "@std/path/posix/dirname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(dirname("https://deno.land/std/path/mod.ts"), "https://deno.land/std/path");
+ * assertEquals(dirname("https://deno.land/std/path/mod.ts?a=b"), "https://deno.land/std/path");
+ * assertEquals(dirname("https://deno.land/std/path/mod.ts#header"), "https://deno.land/std/path");
  * ```
  *
  * Note: If you are working with file URLs,

path/posix/extname.ts

@@ -18,6 +18,22 @@ import { isPosixPathSeparator } from "./_util.ts";
  * assertEquals(extname("/home/user/Documents/image.png"), ".png");
  * ```
  *
+ * @example Working with URLs
+ *
+ * Note: This function doesn't automatically strip hash and query parts from
+ * URLs. If your URL contains a hash or query, remove them before passing the
+ * URL to the function. This can be done by passing the URL to `new URL(url)`,
+ * and setting the `hash` and `search` properties to empty strings.
+ *
+ * ```ts
+ * import { extname } from "@std/path/posix/extname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(extname("https://deno.land/std/path/mod.ts"), ".ts");
+ * assertEquals(extname("https://deno.land/std/path/mod.ts?a=b"), ".ts?a=b");
+ * assertEquals(extname("https://deno.land/std/path/mod.ts#header"), ".ts#header");
+ * ```
+ *
  * Note: If you are working with file URLs,
  * use the new version of `extname` from `@std/path/posix/unstable-extname`.
  *

path/posix/join.ts

@@ -16,6 +16,19 @@ import { normalize } from "./normalize.ts";
  * assertEquals(path, "/foo/bar/baz/asdf");
  * ```
  *
+ * @example Working with URLs
+ * ```ts
+ * import { join } from "@std/path/posix/join";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const url = new URL("https://deno.land");
+ * url.pathname = join("std", "path", "mod.ts");
+ * assertEquals(url.href, "https://deno.land/std/path/mod.ts");
+ *
+ * url.pathname = join("//std", "path/", "/mod.ts");
+ * assertEquals(url.href, "https://deno.land/std/path/mod.ts");
+ * ```
+ *
  * Note: If you are working with file URLs,
  * use the new version of `join` from `@std/path/posix/unstable-join`.
  *

path/posix/mod.ts

@@ -6,6 +6,13 @@
 /**
  * Utilities for working with POSIX-formatted paths.
  *
+ * This module also provides some functions that help when working with URLs.
+ * See the documentation for examples.
+ *
+ * Codes in the examples uses POSIX path but it automatically use Windows path
+ * on Windows. Use methods under `posix` or `win32` object instead to handle non
+ * platform specific path like:
+ *
  * ```ts
  * import { fromFileUrl } from "@std/path/posix/from-file-url";
  * import { assertEquals } from "@std/assert";

path/posix/normalize.ts

@@ -19,6 +19,24 @@ import { isPosixPathSeparator } from "./_util.ts";
  * assertEquals(path, "/foo/bar/baz/asdf");
  * ```
  *
+ * @example Working with URLs
+ *
+ * Note: This function will remove the double slashes from a URL's scheme.
+ * Hence, do not pass a full URL to this function. Instead, pass the pathname of
+ * the URL.
+ *
+ * ```ts
+ * import { normalize } from "@std/path/posix/normalize";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const url = new URL("https://deno.land");
+ * url.pathname = normalize("//std//assert//.//mod.ts");
+ * assertEquals(url.href, "https://deno.land/std/assert/mod.ts");
+ *
+ * url.pathname = normalize("std/assert/../async/retry.ts");
+ * assertEquals(url.href, "https://deno.land/std/async/retry.ts");
+ * ```
+ *
  * Note: If you are working with file URLs,
  * use the new version of `normalize` from `@std/path/posix/unstable-normalize`.
  *