docs(fs): polish documentation (#4526)

* refactor(datetime): rename `_common.ts` to `_date_time_formatter.ts`

* docs(fs): polish documentation

* work

fs/copy.ts

@@ -14,14 +14,15 @@ const isWindows = Deno.build.os === "windows";
 /** Options for {@linkcode copy} and {@linkcode copySync}. */
 export interface CopyOptions {
   /**
-   * overwrite existing file or directory.
+   * Whether to overwrite existing file or directory.
+   *
    * @default {false}
    */
   overwrite?: boolean;
   /**
-   * When `true`, will set last modification and access times to the ones of the
-   * original source files.
-   * When `false`, timestamp behavior is OS-dependent.
+   * When `true`, will set last modification and access times to the ones of
+   * the original source files. When `false`, timestamp behavior is
+   * OS-dependent.
    *
    * @default {false}
    */
@@ -249,21 +250,49 @@ function copyDirSync(
 }
 
 /**
- * Copy a file or directory. The directory can have contents. Like `cp -r`.
+ * Asynchronously copy a file or directory. The directory can have contents.
+ * Like `cp -r`.
+ *
+ * If `src` is a directory it will copy everything inside of this directory,
+ * not the entire directory itself. If `src` is a file, `dest` cannot be a
+ * directory.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
- * @example
+ * @param src The source file/directory path as a string or URL.
+ * @param dest The destination file/directory path as a string or URL.
+ * @param options Options for copying.
+ * @returns A promise that resolves once the copy operation completes.
+ *
+ * @example Basic usage
  * ```ts
  * import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
- * copy("./foo", "./bar"); // returns a promise
+ *
+ * await copy("./foo", "./bar");
+ * ```
+ *
+ * This will copy the file or directory at `./foo` to `./bar` without
+ * overwriting.
+ *
+ * @example Overwriting files/directories
+ * ```ts
+ * import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
+ *
+ * await copy("./foo", "./bar", { overwrite: true });
+ * ```
+ *
+ * This will copy the file or directory at `./foo` to `./bar` and overwrite
+ * any existing files or directories.
+ *
+ * @example Preserving timestamps
+ * ```ts
+ * import { copy } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
+ *
+ * await copy("./foo", "./bar", { preserveTimestamps: true });
  * ```
  *
- * @param src the file/directory path.
- *            Note that if `src` is a directory it will copy everything inside
- *            of this directory, not the entire directory itself
- * @param dest the destination path. Note that if `src` is a file, `dest` cannot
- *             be a directory
- * @param options
+ * This will copy the file or directory at `./foo` to `./bar` and set the
+ * last modification and access times to the ones of the original source files.
  */
 export async function copy(
   src: string | URL,
@@ -295,20 +324,49 @@ export async function copy(
 }
 
 /**
- * Copy a file or directory. The directory can have contents. Like `cp -r`.
+ * Synchronously copy a file or directory. The directory can have contents.
+ * Like `cp -r`.
+ *
+ * If `src` is a directory it will copy everything inside of this directory,
+ * not the entire directory itself. If `src` is a file, `dest` cannot be a
+ * directory.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
- * @example
+ * @param src The source file/directory path as a string or URL.
+ * @param dest The destination file/directory path as a string or URL.
+ * @param options Options for copying.
+ * @returns A void value that returns once the copy operation completes.
+ *
+ * @example Basic usage
  * ```ts
  * import { copySync } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
- * copySync("./foo", "./bar"); // void
+ *
+ * copySync("./foo", "./bar");
  * ```
- * @param src the file/directory path.
- *            Note that if `src` is a directory it will copy everything inside
- *            of this directory, not the entire directory itself
- * @param dest the destination path. Note that if `src` is a file, `dest` cannot
- *             be a directory
- * @param options
+ *
+ * This will copy the file or directory at `./foo` to `./bar` without
+ * overwriting.
+ *
+ * @example Overwriting files/directories
+ * ```ts
+ * import { copySync } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
+ *
+ * copySync("./foo", "./bar", { overwrite: true });
+ * ```
+ *
+ * This will copy the file or directory at `./foo` to `./bar` and overwrite
+ * any existing files or directories.
+ *
+ * @example Preserving timestamps
+ * ```ts
+ * import { copySync } from "https://deno.land/std@$STD_VERSION/fs/copy.ts";
+ *
+ * copySync("./foo", "./bar", { preserveTimestamps: true });
+ * ```
+ *
+ * This will copy the file or directory at `./foo` to `./bar` and set the
+ * last modification and access times to the ones of the original source files.
  */
 export function copySync(
   src: string | URL,

fs/empty_dir.ts

@@ -3,17 +3,20 @@ import { join } from "../path/join.ts";
 import { toPathString } from "./_to_path_string.ts";
 
 /**
- * Ensures that a directory is empty.
- * Deletes directory contents if the directory is not empty.
- * If the directory does not exist, it is created.
+ * Asynchronously ensures that a directory is empty deletes the directory
+ * contents it is not empty. If the directory does not exist, it is created.
  * The directory itself is not deleted.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param dir The path of the directory to empty, as a string or URL.
+ * @returns A void promise that resolves once the directory is empty.
+ *
  * @example
  * ```ts
- * import { emptyDir } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { emptyDir } from "https://deno.land/std@$STD_VERSION/fs/empty_dir.ts";
  *
- * emptyDir("./foo"); // returns a promise
+ * await emptyDir("./foo");
  * ```
  */
 export async function emptyDir(dir: string | URL) {
@@ -37,17 +40,20 @@ export async function emptyDir(dir: string | URL) {
 }
 
 /**
- * Ensures that a directory is empty.
- * Deletes directory contents if the directory is not empty.
- * If the directory does not exist, it is created.
+ * Synchronously ensures that a directory is empty deletes the directory
+ * contents it is not empty. If the directory does not exist, it is created.
  * The directory itself is not deleted.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param dir The path of the directory to empty, as a string or URL.
+ * @returns A void value that returns once the directory is empty.
+ *
  * @example
  * ```ts
- * import { emptyDirSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { emptyDirSync } from "https://deno.land/std@$STD_VERSION/fs/empty_dir.ts";
  *
- * emptyDirSync("./foo"); // void
+ * emptyDirSync("./foo");
  * ```
  */
 export function emptyDirSync(dir: string | URL) {

fs/ensure_dir.ts

@@ -2,15 +2,19 @@
 import { getFileInfoType } from "./_get_file_info_type.ts";
 
 /**
- * Ensures that the directory exists.
- * If the directory structure does not exist, it is created. Like mkdir -p.
+ * Asynchronously ensures that the directory exists. If the directory structure
+ * does not exist, it is created. Like `mkdir -p`.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param dir The path of the directory to ensure, as a string or URL.
+ * @returns A promise that resolves once the directory exists.
+ *
  * @example
  * ```ts
- * import { ensureDir } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureDir } from "https://deno.land/std@$STD_VERSION/fs/ensure_dir.ts";
  *
- * ensureDir("./bar"); // returns a promise
+ * await ensureDir("./bar");
  * ```
  */
 export async function ensureDir(dir: string | URL) {
@@ -51,15 +55,19 @@ export async function ensureDir(dir: string | URL) {
 }
 
 /**
- * Ensures that the directory exists.
- * If the directory structure does not exist, it is created. Like mkdir -p.
+ * Synchronously ensures that the directory exists. If the directory structure
+ * does not exist, it is created. Like `mkdir -p`.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param dir The path of the directory to ensure, as a string or URL.
+ * @returns A void value that returns once the directory exists.
+ *
  * @example
  * ```ts
- * import { ensureDirSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureDir } from "https://deno.land/std@$STD_VERSION/fs/ensure_dir.ts";
  *
- * ensureDirSync("./ensureDirSync"); // void
+ * await ensureDir("./bar");
  * ```
  */
 export function ensureDirSync(dir: string | URL) {

fs/ensure_file.ts

@@ -5,18 +5,20 @@ import { getFileInfoType } from "./_get_file_info_type.ts";
 import { toPathString } from "./_to_path_string.ts";
 
 /**
- * Ensures that the file exists.
- * If the file that is requested to be created is in directories that do not
- * exist.
- * these directories are created. If the file already exists,
- * it is NOTMODIFIED.
+ * Asynchronously ensures that the file exists. If the file that is requested to
+ * be created is in directories that do not exist, these directories are created.
+ * If the file already exists, it is not modified.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param filePath The path of the file to ensure, as a string or URL.
+ * @returns A void promise that resolves once the file exists.
+ *
  * @example
  * ```ts
- * import { ensureFile } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureFile } from "https://deno.land/std@$STD_VERSION/fs/ensure_file.ts";
  *
- * ensureFile("./folder/targetFile.dat"); // returns promise
+ * await ensureFile("./folder/targetFile.dat");
  * ```
  */
 export async function ensureFile(filePath: string | URL): Promise<void> {
@@ -43,18 +45,20 @@ export async function ensureFile(filePath: string | URL): Promise<void> {
 }
 
 /**
- * Ensures that the file exists.
- * If the file that is requested to be created is in directories that do not
- * exist,
- * these directories are created. If the file already exists,
- * it is NOT MODIFIED.
+ * Synchronously ensures that the file exists. If the file that is requested to
+ * be created is in directories that do not exist, these directories are created.
+ * If the file already exists, it is not modified.
+ *
  * Requires the `--allow-read` and `--allow-write` flag.
  *
+ * @param filePath The path of the file to ensure, as a string or URL.
+ * @returns A void value that returns once the file exists.
+ *
  * @example
  * ```ts
- * import { ensureFileSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureFileSync } from "https://deno.land/std@$STD_VERSION/fs/ensure_file.ts";
  *
- * ensureFileSync("./folder/targetFile.dat"); // void
+ * ensureFileSync("./folder/targetFile.dat");
  * ```
  */
 export function ensureFileSync(filePath: string | URL): void {

fs/ensure_link.ts

@@ -4,18 +4,20 @@ import { ensureDir, ensureDirSync } from "./ensure_dir.ts";
 import { toPathString } from "./_to_path_string.ts";
 
 /**
- * Ensures that the hard link exists.
- * If the directory structure does not exist, it is created.
+ * Asynchronously ensures that the hard link exists. If the directory structure
+ * does not exist, it is created.
+ *
+ * @param src The source file path as a string or URL. Directory hard links are
+ * not allowed.
+ * @param dest The destination link path as a string or URL.
+ * @returns A void promise that resolves once the hard link exists.
  *
  * @example
  * ```ts
- * import { ensureSymlink } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureLink } from "https://deno.land/std@$STD_VERSION/fs/ensure_link.ts";
  *
- * ensureSymlink("./folder/targetFile.dat", "./folder/targetFile.link.dat"); // returns promise
+ * await ensureLink("./folder/targetFile.dat", "./folder/targetFile.link.dat");
  * ```
- *
- * @param src the source file path. Directory hard links are not allowed.
- * @param dest the destination link path
  */
 export async function ensureLink(src: string | URL, dest: string | URL) {
   dest = toPathString(dest);
@@ -25,18 +27,20 @@ export async function ensureLink(src: string | URL, dest: string | URL) {
 }
 
 /**
- * Ensures that the hard link exists.
- * If the directory structure does not exist, it is created.
+ * Synchronously ensures that the hard link exists. If the directory structure
+ * does not exist, it is created.
+ *
+ * @param src The source file path as a string or URL. Directory hard links are
+ * not allowed.
+ * @param dest The destination link path as a string or URL.
+ * @returns A void value that returns once the hard link exists.
  *
  * @example
  * ```ts
- * import { ensureSymlinkSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ * import { ensureLinkSync } from "https://deno.land/std@$STD_VERSION/fs/ensure_link.ts";
  *
- * ensureSymlinkSync("./folder/targetFile.dat", "./folder/targetFile.link.dat"); // void
+ * ensureLinkSync("./folder/targetFile.dat", "./folder/targetFile.link.dat");
  * ```
- *
- * @param src the source file path. Directory hard links are not allowed.
- * @param dest the destination link path
  */
 export function ensureLinkSync(src: string | URL, dest: string | URL) {
   dest = toPathString(dest);