docs(fs): polish documentation

datetime/_common.ts → datetime/_date_time_formatter.ts

@@ -1,34 +1,34 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-export type Token = {
+type Token = {
   type: string;
   value: string | number;
   index: number;
   [key: string]: unknown;
 };
 
-export interface ReceiverResult {
+interface ReceiverResult {
   [name: string]: string | number | unknown;
 }
-export type CallbackResult = {
+type CallbackResult = {
   type: string;
   value: string | number;
   [key: string]: unknown;
 };
 type CallbackFunction = (value: unknown) => CallbackResult;
 
-export type TestResult = { value: unknown; length: number } | undefined;
-export type TestFunction = (
+type TestResult = { value: unknown; length: number } | undefined;
+type TestFunction = (
   string: string,
 ) => TestResult | undefined;
 
-export interface Rule {
+interface Rule {
   test: TestFunction;
   fn: CallbackFunction;
 }
 
-export class Tokenizer {
+class Tokenizer {
   rules: Rule[];
 
   constructor(rules: Rule[] = []) {

datetime/format.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import { DateTimeFormatter } from "./_common.ts";
+import { DateTimeFormatter } from "./_date_time_formatter.ts";
 
 /**
  * Takes an input `date` and a `formatString` to format to a `string`.

datetime/parse.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import { DateTimeFormatter } from "./_common.ts";
+import { DateTimeFormatter } from "./_date_time_formatter.ts";
 
 /**
  * Takes an input `string` and a `formatString` to parse to a `date`.

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 {