docs(path): add examples to @std/path/posix examples (denoland#5371)

* docs(path): add examples to `@std/path/posix` examples

* work

Author: iuioiua

path/mod.ts

@@ -31,6 +31,9 @@
  * assertEquals(fromFileUrl("file:///home/foo"), "\\home\\foo");
  * ```
  *
+ * Functions for working with URLs can be found in
+ * {@link ./doc/posix/~ | @std/path/posix}.
+ *
  * @module
  */
 export * from "./basename.ts";

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");
+ * ```
+ *
  * @param path The path to extract the name from.
  * @param suffix The suffix to remove from extracted name.
  * @returns The extracted name.

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");
  * ```
  *
  * @param path The path to get the directory from.

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");
+ * ```
+ *
  * @param path The path to get the extension from.
  * @returns The extension (ex. for `file.ts` returns `.ts`).
  */

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");
+ * ```
+ *
  * @param paths The paths to join.
  * @returns The joined path.
  */

path/posix/mod.ts

@@ -6,6 +6,9 @@
 /**
  * Utilities for working with OS-specific file 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:

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");
+ * ```
+ *
  * @param path The path to normalize.
  * @returns The normalized path.
  */