From af1181038950e5f906743feb97de35db8dddd319 Mon Sep 17 00:00:00 2001 From: segayuu Date: Tue, 5 Sep 2017 11:22:38 +0900 Subject: [PATCH] added doc comments. --- types/hexo-fs/index.d.ts | 147 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 1 deletion(-) diff --git a/types/hexo-fs/index.d.ts b/types/hexo-fs/index.d.ts index eae1e79c06..8a0e96ebaa 100644 --- a/types/hexo-fs/index.d.ts +++ b/types/hexo-fs/index.d.ts @@ -68,7 +68,7 @@ import { unwatchFile, // write, writeSync - } from 'graceful-fs'; +} from 'graceful-fs'; export interface DirectoryOptions { ignoreHidden?: boolean; @@ -91,8 +91,27 @@ export let access: ((path: PathLike, mode?: number) => Promise) | undefine export let accessSync: ((path: PathLike, mode?: number) => void) | undefined; // promisify // appendFile +/** + * Appends data to a file. + * @param path + * @param data + * @param callback + */ export function appendFile(path: string, data: any, callback?: (err: any) => void): Promise; +/** + * Appends data to a file. + * @param path + * @param data + * @param options + * @param callback + */ export function appendFile(path: string, data: any, options: string | AppendFileOptions, callback?: (err: any) => void): Promise; +/** + * Synchronous version of fs.appendFile. + * @param path + * @param data + * @param options + */ export function appendFileSync(path: string, data: any, options?: string | AppendFileOptions): void; // chmod @@ -112,14 +131,37 @@ export function close(fd: number): Promise; // promisify export { closeSync }; // copy +/** + * Copies a directory from src to dest. It returns an array of copied files. + * @param src + * @param dest + * @param callback + */ export function copyDir(src: string, dest: string, callback?: (err: any, value?: string[]) => void): Promise; +/** + * Copies a directory from src to dest. It returns an array of copied files. + * @param dest + * @param options + * @param callback + */ export function copyDir(src: string, dest: string, options?: DirectoryOptions, callback?: (err: any, value?: string[]) => void): Promise; +/** + * Copies a file from src to dest. + * @param src + * @param dest + * @param callback + */ export function copyFile(src: PathLike, dest: string, callback?: (err: any) => void): Promise; // createStream export { createReadStream, createWriteStream }; // emptyDir +/** + * Deletes all files in a directory. It returns an array of deleted files. + * @param path + * @param callback + */ export function emptyDir(path: string, callback?: (err: any, value?: string | string[]) => void): Promise; export function emptyDir( path: string, @@ -129,11 +171,31 @@ export function emptyDir( export function emptyDirSync(path: string, options?: DirectoryOptions & { exclude?: string[] }, parent?: string): string | string[]; // ensurePath +/** + * Ensures the given path is available to use or appends a number to the path. + * @param path + * @param callback + */ export function ensurePath(path: string, callback?: (err: any, value?: string) => void): Promise; +/** + * Synchronous version of `fs.ensurePath`. + * @param path + */ export function ensurePathSync(path: string): string; // ensureWriteStream +/** + * Creates the parent directories if they does not exist and returns a writable stream. + * @param path + * @param callback + */ export function ensureWriteStream(path: string, callback?: (err: any, value?: WriteStream) => void): Promise; +/** + * Creates the parent directories if they does not exist and returns a writable stream. + * @param path + * @param options + * @param callback + */ export function ensureWriteStream( path: string, options?: string | { @@ -146,6 +208,11 @@ export function ensureWriteStream( }, callback?: (err: any, value?: WriteStream) => void ): Promise; +/** + * Synchronous version of fs.ensureWriteStream. + * @param path + * @param options + */ export function ensureWriteStreamSync(path: string, options?: string | { flags?: string; defaultEncoding?: string; @@ -156,7 +223,16 @@ export function ensureWriteStreamSync(path: string, options?: string | { }): WriteStream; // exists +/** + * Test whether or not the given `path` exists by checking with the file system. + * @param path checking if exists. + * @param callback + */ export function exists(path: PathLike, callback?: (exist: boolean) => void): Promise; +/** + * Synchronous version of `fs.exists`. + * @param path + */ export function existsSync(path: PathLike): boolean; // fsync @@ -168,8 +244,25 @@ export function link(existingPath: PathLike, newPath: PathLike): Promise; export { linkSync }; // listDir +/** + * Lists files in a directory. + * @param path + * @param callback + */ export function listDir(path: string, callback?: (err: any, value?: string[]) => void): Promise; +/** + * Lists files in a directory. + * @param path + * @param options + * @param callback + */ export function listDir(path: string, options?: DirectoryOptions, callback?: (err: any, value?: string[]) => void): Promise; +/** + * Synchronous version of `fs.listDir`. + * @param path + * @param options + * @param parent + */ export function listDirSync(path: string, options?: DirectoryOptions, parent?: string): string | string[]; // mkdir @@ -177,7 +270,16 @@ export function mkdir(path: PathLike, mode?: string | number): Promise; // export { mkdirSync }; // mkdirs +/** + * Creates a directory and its parent directories if they does not exist. + * @param path + * @param callback + */ export function mkdirs(path: PathLike, callback?: (err: any) => void): Promise; +/** + * Synchronous version of `fs.mkdirs`. + * @param path + */ export function mkdirsSync(path: string): void; // open @@ -206,12 +308,28 @@ export function readdir( export { readdirSync }; // readFile +/** + * Reads the entire contents of a file. + * @param path + * @param callback + */ export function readFile(path: PathLike | number, callback?: (err: any, value?: string) => void): Promise; +/** + * Reads the entire contents of a file. + * @param path + * @param options + * @param callback + */ export function readFile( path: PathLike | number, options?: { encoding?: string; flag?: string; escape?: boolean; }, callback?: (err: any, value?: string) => void ): Promise; +/** + * Synchronous version of `fs.readFile`. + * @param path + * @param options + */ export function readFileSync(path: PathLike | number, options?: { encoding?: string; flag?: string; escape?: boolean; }): string; // readlink @@ -256,6 +374,14 @@ export { utimesSync, futimesSync }; // watch import { FSWatcher, WatchOptions } from 'chokidar'; +/** + * Watches changes of a file or a directory. + * + * See Chokidar API for more info. + * @param path + * @param options + * @param callback + */ export function watch(path: string | string[], options?: WatchOptions, callback?: (err: any, value?: FSWatcher) => void): Promise; export { watchFile, unwatchFile }; @@ -276,13 +402,32 @@ export function write( export { writeSync }; // writeFile +/** + * Writes data to a file. + * @param path + * @param data + * @param callback + */ export function writeFile(path: string, data: any, callback?: (err: any) => void): Promise; +/** + * Writes data to a file. + * @param path + * @param data + * @param options + * @param callback + */ export function writeFile( path: string, data: any, options?: string | { encoding?: string | null; mode?: string | number; flag?: string }, callback?: (err: any) => void ): Promise; +/** + * Synchronous version of `fs.writeFile`. + * @param path + * @param data + * @param options + */ export function writeFileSync(path: string, data: any, options?: string | { encoding?: string | null; mode?: string | number; flag?: string }): void; // Static classes