chore(fs): complete documentation

fs/_util.ts

@@ -56,11 +56,16 @@ export function getFileInfoType(fileInfo: Deno.FileInfo): PathType | undefined {
     : undefined;
 }
 
+/**
+ * Walk entry for {@linkcode walk}, {@linkcode walkSync},
+ * {@linkcode expandGlob} and {@linkcode expandGlobSync}.
+ */
 export interface WalkEntry extends Deno.DirEntry {
+  /** Full path of the entry. */
   path: string;
 }
 
-/** Create WalkEntry for the `path` synchronously */
+/** Create {@linkcode WalkEntry} for the `path` synchronously. */
 export function createWalkEntrySync(path: string | URL): WalkEntry {
   path = toPathString(path);
   path = normalize(path);
@@ -75,7 +80,7 @@ export function createWalkEntrySync(path: string | URL): WalkEntry {
   };
 }
 
-/** Create WalkEntry for the `path` asynchronously */
+/** Create {@linkcode WalkEntry} for the `path` asynchronously. */
 export async function createWalkEntry(path: string | URL): Promise<WalkEntry> {
   path = toPathString(path);
   path = normalize(path);

fs/copy.ts

@@ -9,6 +9,7 @@ import { assert } from "../assert/assert.ts";
 
 const isWindows = Deno.build.os === "windows";
 
+/** Options for {@linkcode copy} and {@linkcode copySync}. */
 export interface CopyOptions {
   /**
    * overwrite existing file or directory.

fs/ensure_file.ts

@@ -18,7 +18,7 @@ import { getFileInfoType, toPathString } from "./_util.ts";
  * ensureFile("./folder/targetFile.dat"); // returns promise
  * ```
  */
-export async function ensureFile(filePath: string | URL) {
+export async function ensureFile(filePath: string | URL): Promise<void> {
   try {
     // if file exists
     const stat = await Deno.lstat(filePath);
@@ -56,7 +56,7 @@ export async function ensureFile(filePath: string | URL) {
  * ensureFileSync("./folder/targetFile.dat"); // void
  * ```
  */
-export function ensureFileSync(filePath: string | URL) {
+export function ensureFileSync(filePath: string | URL): void {
   try {
     // if file exists
     const stat = Deno.lstatSync(filePath);

fs/eol.ts

@@ -1,6 +1,6 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 
-// End-of-line character for POSIX platforms such as macOS and Linux.
+/** End-of-line character for POSIX platforms such as macOS and Linux. */
 export const LF = "\n" as const;
 
 /** End-of-line character for Windows platforms. */
@@ -16,7 +16,7 @@
  * EOL; // Returns "\n" on POSIX platforms or "\r\n" on Windows
  * ```
  */
-export const EOL = Deno?.build.os === "windows" ? CRLF : LF;
+export const EOL: "\n" | "\r\n" = Deno?.build.os === "windows" ? CRLF : LF;
 
 const regDetect = /(?:\r?\n)/g;
 

fs/exists.ts

@@ -1,5 +1,6 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 
+/** Options for {@linkcode exists} and {@linkcode existsSync.} */
 export interface ExistsOptions {
   /**
    * When `true`, will check if the path is readable by the user as well.

fs/expand_glob.ts

@@ -11,17 +11,32 @@ import {
   toPathString,
   WalkEntry,
 } from "./_util.ts";
+export type { GlobOptions };
 
 const isWindows = Deno.build.os === "windows";
 
+/** Options for {@linkcode expandGlob} and {@linkcode expandGlobSync}. */
 export interface ExpandGlobOptions extends Omit<GlobOptions, "os"> {
+  /** File path where to expand from. */
   root?: string;
+  /** List of glob patterns to be excluded from the expansion. */
   exclude?: string[];
+  /**
+   * Whether to include directories in entries.
+   *
+   * @default {true}
+   */
   includeDirs?: boolean;
+  /**
+   * Whether to follow symbolic links.
+   *
+   * @default {false}
+   */
   followSymlinks?: boolean;
   /**
    * Indicates whether the followed symlink's path should be canonicalized.
    * This option works only if `followSymlinks` is not `false`.
+   *
    * @default {true}
    */
   canonicalize?: boolean;

fs/move.ts

@@ -3,15 +3,26 @@ import { isSamePath, isSubdir } from "./_util.ts";
 
 const EXISTS_ERROR = new Deno.errors.AlreadyExists("dest already exists.");
 
+/**
+ * Error thrown in {@linkcode move} or {@linkcode moveSync} when the
+ * destination is a subdirectory of the source.
+ */
 export class SubdirectoryMoveError extends Error {
+  /** Constructs a new instance. */
   constructor(src: string | URL, dest: string | URL) {
     super(
       `Cannot move '${src}' to a subdirectory of itself, '${dest}'.`,
     );
   }
 }
 
-interface MoveOptions {
+/** Options for {@linkcode move} and {@linkcode moveSync}. */
+export interface MoveOptions {
+  /**
+   * Whether the destination file should be overwritten if it already exists.
+   *
+   * @default {false}
+   */
   overwrite?: boolean;
 }
 
@@ -29,7 +40,7 @@ export async function move(
   src: string | URL,
   dest: string | URL,
   { overwrite = false }: MoveOptions = {},
-) {
+): Promise<void> {
   const srcStat = await Deno.stat(src);
 
   if (
@@ -62,6 +73,7 @@ export async function move(
 
 /**
  * Moves a file or directory synchronously.
+ *
  * @example
  * ```ts
  * import { moveSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
@@ -73,7 +85,7 @@ export function moveSync(
   src: string | URL,
   dest: string | URL,
   { overwrite = false }: MoveOptions = {},
-) {
+): void {
   const srcStat = Deno.statSync(src);
 
   if (

fs/walk.ts

@@ -11,17 +11,19 @@
   WalkEntry,
 } from "./_util.ts";
 
+/** Error thrown in {@linkcode walk} or {@linkcode walkSync} during iteration. */
 export class WalkError extends Error {
-  override cause: unknown;
-  override name = "WalkError";
-  path: string;
+  /** File path of the root that's being walked. */
+  root: string;
 
-  constructor(cause: unknown, path: string) {
+  /** Constructs a new instance. */
+  constructor(cause: unknown, root: string) {
     super(
-      `${cause instanceof Error ? cause.message : cause} for path "${path}"`,
+      `${cause instanceof Error ? cause.message : cause} for path "${root}"`,
     );
-    this.path = path;
     this.cause = cause;
+    this.name = "WalkError";
+    this.root = root;
   }
 }
 
@@ -48,6 +50,7 @@
   return new WalkError(err, root);
 }
 
+/** Options for {@linkcode walk} and {@linkcode walkSync}. */
 export interface WalkOptions {
   /**
    * The maximum depth of the file tree to be walked recursively.

path/_common/glob_to_reg_exp.ts

@@ -1,6 +1,7 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
+/** Options for {@linkcode globToRegExp}. */
 export interface GlobOptions {
   /** Extended glob syntax.
    * See https://www.linuxjournal.com/content/bash-extended-globbing.