Improve docs (#795)

* improve docs * Update docs/ensureSymlink-sync.md Co-authored-by: Ryan Zimmerman <17342435+RyanZim@users.noreply.github.com> * Update docs/ensureSymlink.md Co-authored-by: Ryan Zimmerman <17342435+RyanZim@users.noreply.github.com> * add Error type to docs Co-authored-by: Ryan Zimmerman <17342435+RyanZim@users.noreply.github.com>
jprichardson · May 11, 2020 · b0eb751 · b0eb751
1 parent a2738d3
commit b0eb751
Show file tree

Hide file tree

Showing 24 changed files with 77 additions and 72 deletions.
diff --git a/docs/copy-sync.md b/docs/copy-sync.md
@@ -1,6 +1,6 @@
 # copySync(src, dest[, options])
 
-Copy a file or directory. The directory can have contents. Like `cp -r`.
+Copy a file or directory. The directory can have contents.
 
 - `src` `<String>` Note that if `src` is a directory it will copy everything inside of this directory, not the entire directory itself (see [issue #537](https://github.com/jprichardson/node-fs-extra/issues/537)).
 - `dest` `<String>` Note that if `src` is a file, `dest` cannot be a directory (see [issue #323](https://github.com/jprichardson/node-fs-extra/issues/323)).

diff --git a/docs/copy.md b/docs/copy.md
@@ -1,6 +1,6 @@
 # copy(src, dest[, options][, callback])
 
-Copy a file or directory. The directory can have contents. Like `cp -r`.
+Copy a file or directory. The directory can have contents.
 
 - `src` `<String>` Note that if `src` is a directory it will copy everything inside of this directory, not the entire directory itself (see [issue #537](https://github.com/jprichardson/node-fs-extra/issues/537)).
 - `dest` `<String>` Note that if `src` is a file, `dest` cannot be a directory (see [issue #323](https://github.com/jprichardson/node-fs-extra/issues/323)).
@@ -11,6 +11,7 @@ Copy a file or directory. The directory can have contents. Like `cp -r`.
   - `preserveTimestamps` `<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. Default is `false`.
   - `filter` `<Function>`: Function to filter copied files. Return `true` to include, `false` to exclude. Can also return a `Promise` that resolves to `true` or `false` (or pass in an `async` function).
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 
@@ -20,13 +21,11 @@ const fs = require('fs-extra')
 // With a callback:
 fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
   if (err) return console.error(err)
-
   console.log('success!')
 }) // copies file
 
 fs.copy('/tmp/mydir', '/tmp/mynewdir', err => {
   if (err) return console.error(err)
-
   console.log('success!')
 }) // copies directory, even if it has subdirectories or files
 
@@ -64,7 +63,6 @@ const filterFunc = (src, dest) => {
 
 fs.copy('/tmp/mydir', '/tmp/mynewdir', { filter: filterFunc }, err => {
   if (err) return console.error(err)
-
   console.log('success!')
 })
 ```
diff --git a/docs/emptyDir.md b/docs/emptyDir.md
@@ -6,6 +6,7 @@ Ensures that a directory is empty. Deletes directory contents if the directory i
 
 - `dir` `<String>`
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 
@@ -16,7 +17,6 @@ const fs = require('fs-extra')
 // With a callback:
 fs.emptyDir('/tmp/some/dir', err => {
   if (err) return console.error(err)
-
   console.log('success!')
 })
 

diff --git a/docs/ensureDir-sync.md b/docs/ensureDir-sync.md
@@ -1,11 +1,14 @@
 # ensureDirSync(dir[,options])
 
-Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`. If provided, options may specify the desired mode for the directory. 
+Ensures that the directory exists. If the directory structure does not exist, it is created. If provided, options may specify the desired mode for the directory. 
 
 **Aliases:** `mkdirsSync()`, `mkdirpSync()`
 
 - `dir` `<String>`
 - `options` `<Integer>|<Object>`
+  - If it is `Integer`, it will be `mode`.
+  - If it is `Object`, it will be `{ mode: <Integer> }`.
+
 ## Example:
 
 ```js

diff --git a/docs/ensureDir.md b/docs/ensureDir.md
@@ -1,12 +1,15 @@
 # ensureDir(dir[,options][,callback])
 
-Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`.
+Ensures that the directory exists. If the directory structure does not exist, it is created.
 
 **Aliases:** `mkdirs()`, `mkdirp()`
 
 - `dir` `<String>`
 - `options` `<Integer>|<Object>`
+  - If it is `Integer`, it will be `mode`.
+  - If it is `Object`, it will be `{ mode: <Integer> }`.
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 

diff --git a/docs/ensureFile.md b/docs/ensureFile.md
@@ -6,6 +6,7 @@ Ensures that the file exists. If the file that is requested to be created is in
 
 - `file` `<String>`
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 

diff --git a/docs/ensureLink-sync.md b/docs/ensureLink-sync.md
@@ -1,19 +1,19 @@
-# ensureLinkSync(srcpath, dstpath)
+# ensureLinkSync(srcPath, destPath)
 
 Ensures that the link exists. If the directory structure does not exist, it is created.
 
 **Alias:** `createLinkSync()`
 
-- `srcpath` `<String>`
-- `dstpath` `<String>`
+- `srcPath` `<String>`
+- `destPath` `<String>`
 
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
-const srcpath = '/tmp/file.txt'
-const dstpath = '/tmp/this/path/does/not/exist/file.txt'
-fs.ensureLinkSync(srcpath, dstpath)
+const srcPath = '/tmp/file.txt'
+const destPath = '/tmp/this/path/does/not/exist/file.txt'
+fs.ensureLinkSync(srcPath, destPath)
 // link has now been created, including the directory it is to be placed in
 ```
diff --git a/docs/ensureLink.md b/docs/ensureLink.md
@@ -1,29 +1,30 @@
-# ensureLink(srcpath, dstpath[, callback])
+# ensureLink(srcPath, destPath[, callback])
 
 Ensures that the link exists. If the directory structure does not exist, it is created.
 
 **Alias:** `createLink()`
 
-- `srcpath` `<String>`
-- `dstpath` `<String>`
+- `srcPath` `<String>`
+- `destPath` `<String>`
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
-const srcpath = '/tmp/file.txt'
-const dstpath = '/tmp/this/path/does/not/exist/file.txt'
+const srcPath = '/tmp/file.txt'
+const destPath = '/tmp/this/path/does/not/exist/file.txt'
 
 // With a callback:
-fs.ensureLink(srcpath, dstpath, err => {
+fs.ensureLink(srcPath, destPath, err => {
   console.log(err) // => null
   // link has now been created, including the directory it is to be placed in
 })
 
 // With Promises:
-fs.ensureLink(srcpath, dstpath)
+fs.ensureLink(srcPath, destPath)
 .then(() => {
   console.log('success!')
 })
@@ -41,5 +42,5 @@ async function example (src, dest) {
   }
 }
 
-example(srcpath, dstpath)
+example(srcPath, destPath)
 ```
diff --git a/docs/ensureSymlink-sync.md b/docs/ensureSymlink-sync.md
@@ -1,20 +1,20 @@
-# ensureSymlinkSync(srcpath, dstpath[, type])
+# ensureSymlinkSync(srcPath, destPath[, type])
 
 Ensures that the symlink exists. If the directory structure does not exist, it is created.
 
 **Alias:** `createSymlinkSync()`
 
-- `srcpath` `<String>`
-- `dstpath` `<String>`
-- `type` `<String>`
+- `srcPath` `<String>`
+- `destPath` `<String>`
+- `type` `<String>` It is only available on Windows and ignored on other platforms. It can be set to `dir`, `file`, or `junction`.
 
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
-const srcpath = '/tmp/file.txt'
-const dstpath = '/tmp/this/path/does/not/exist/file.txt'
-fs.ensureSymlinkSync(srcpath, dstpath)
+const srcPath = '/tmp/file.txt'
+const destPath = '/tmp/this/path/does/not/exist/file.txt'
+fs.ensureSymlinkSync(srcPath, destPath)
 // symlink has now been created, including the directory it is to be placed in
 ```
diff --git a/docs/ensureSymlink.md b/docs/ensureSymlink.md
@@ -1,30 +1,31 @@
-# ensureSymlink(srcpath, dstpath[, type][, callback])
+# ensureSymlink(srcPath, destPath[, type][, callback])
 
 Ensures that the symlink exists. If the directory structure does not exist, it is created.
 
 **Alias:** `createSymlink()`
 
-- `srcpath` `<String>`
-- `dstpath` `<String>`
-- `type` `<String>`
+- `srcPath` `<String>`
+- `destPath` `<String>`
+- `type` `<String>` It is only available on Windows and ignored on other platforms. It can be set to `dir`, `file`, or `junction`.
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
-const srcpath = '/tmp/file.txt'
-const dstpath = '/tmp/this/path/does/not/exist/file.txt'
+const srcPath = '/tmp/file.txt'
+const destPath = '/tmp/this/path/does/not/exist/file.txt'
 
 // With a callback:
-fs.ensureSymlink(srcpath, dstpath, err => {
+fs.ensureSymlink(srcPath, destPath, err => {
   console.log(err) // => null
   // symlink has now been created, including the directory it is to be placed in
 })
 
 // With Promises:
-fs.ensureSymlink(srcpath, dstpath)
+fs.ensureSymlink(srcPath, destPath)
 .then(() => {
   console.log('success!')
 })
@@ -42,5 +43,5 @@ async function example (src, dest) {
   }
 }
 
-example(srcpath, dstpath)
+example(srcPath, destPath)
 ```
diff --git a/docs/move-sync.md b/docs/move-sync.md
@@ -20,5 +20,5 @@ fs.moveSync('/tmp/somefile', '/tmp/does/not/exist/yet/somefile')
 ```js
 const fs = require('fs-extra')
 
-fs.moveSync('/tmp/somedir', '/tmp/may/already/existed/somedir', { overwrite: true })
+fs.moveSync('/tmp/somedir', '/tmp/may/already/exist/somedir', { overwrite: true })
 ```
diff --git a/docs/move.md b/docs/move.md
@@ -7,24 +7,24 @@ Moves a file or directory, even across devices.
 - `options` `<Object>`
   - `overwrite` `<boolean>`: overwrite existing file or directory, default is `false`.
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 
 ```js
 const fs = require('fs-extra')
 
-const srcpath = '/tmp/file.txt'
-const dstpath = '/tmp/this/path/does/not/exist/file.txt'
+const src = '/tmp/file.txt'
+const dest = '/tmp/this/path/does/not/exist/file.txt'
 
 // With a callback:
-fs.move(srcpath, dstpath, err => {
+fs.move(src, dest, err => {
   if (err) return console.error(err)
-
   console.log('success!')
 })
 
 // With Promises:
-fs.move(srcpath, dstpath)
+fs.move(src, dest)
 .then(() => {
   console.log('success!')
 })
@@ -35,24 +35,23 @@ fs.move(srcpath, dstpath)
 // With async/await:
 async function example (src, dest) {
   try {
-    await fs.move(srcpath, dstpath)
+    await fs.move(src, dest)
     console.log('success!')
   } catch (err) {
     console.error(err)
   }
 }
 
-example(srcpath, dstpath)
+example(src, dest)
 ```
 
 **Using `overwrite` option**
 
 ```js
 const fs = require('fs-extra')
 
-fs.move('/tmp/somedir', '/tmp/may/already/existed/somedir', { overwrite: true }, err => {
+fs.move('/tmp/somedir', '/tmp/may/already/exist/somedir', { overwrite: true }, err => {
   if (err) return console.error(err)
-
   console.log('success!')
 })
 ```
diff --git a/docs/outputFile-sync.md b/docs/outputFile-sync.md
@@ -1,10 +1,10 @@
 # outputFileSync(file, data[, options])
 
-Almost the same as `writeFileSync` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). `options` are what you'd pass to [`fs.writeFileSync()`](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options).
+Almost the same as `writeFileSync` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed).
 
 - `file` `<String>`
 - `data` `<String> | <Buffer> | <Uint8Array>`
-- `options` `<Object> | <String>`
+- `options` `<Object> | <String>` (the same as [`fs.writeFileSync()` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options))
 
 ## Example:
 

diff --git a/docs/outputFile.md b/docs/outputFile.md
@@ -1,11 +1,12 @@
 # outputFile(file, data[, options][, callback])
 
-Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback).
+Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed).
 
 - `file` `<String>`
 - `data` `<String> | <Buffer> | <Uint8Array>`
-- `options` `<Object> | <String>`
+- `options` `<Object> | <String>` (the same as [`fs.writeFile()` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback))
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 

diff --git a/docs/outputJson-sync.md b/docs/outputJson-sync.md
@@ -10,7 +10,7 @@ Almost the same as [`writeJsonSync`](writeJson-sync.md), except that if the dire
   - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info.
   - `EOL` `<String>` Set EOL character. Default is `\n`.
   - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter)
-  - Also accepts [`fs.writeFileSync` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options)
+  - Also accepts [`fs.writeFileSync()` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options)
 
 ## Example:
 

diff --git a/docs/outputJson.md b/docs/outputJson.md
@@ -10,8 +10,9 @@ Almost the same as [`writeJson`](writeJson.md), except that if the directory doe
   - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info.
   - `EOL` `<String>` Set EOL character. Default is `\n`.
   - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter)
-  - Also accepts [`fs.writeFile` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback)
+  - Also accepts [`fs.writeFile()` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback)
 - `callback` `<Function>`
+  - `err` `<Error>`
 
 ## Example:
 

diff --git a/docs/pathExists.md b/docs/pathExists.md
@@ -4,6 +4,8 @@ Test whether or not the given path exists by checking with the file system. Like
 
 - `file` `<String>`
 - `callback` `<Function>`
+  - `err` `<Error>`
+  - `exists` `<boolean>`
 
 ## Example:
 

diff --git a/docs/readJson-sync.md b/docs/readJson-sync.md
@@ -1,12 +1,11 @@
 # readJsonSync(file[, options])
 
-Reads a JSON file and then parses it into an object. `options` are the same
-that you'd pass to [`jsonFile.readFileSync`](https://github.com/jprichardson/node-jsonfile#readfilesyncfilename-options).
+Reads a JSON file and then parses it into an object.
 
 **Alias:** `readJSONSync()`
 
 - `file` `<String>`
-- `options` `<Object>`
+- `options` `<Object>` (the same as [`jsonFile.readFileSync()` options](https://github.com/jprichardson/node-jsonfile#readfilesyncfilename-options))
 
 ## Example: