fs,doc: docs-deprecate fs.readdir{Sync}()

It's time overdue for these to start going away.

`fs.opendir()` was introduced over a year ago in
nodejs/node#29349 - which stated
a follow-up of:
"Aliasing fs.readdir to fs.scandir and doing a deprecation."

This provides the intial docs deprecation to both `fs.readdir()`
and `fs.readdirSync()`, both of which are misnamed, and
the former of which is a trap as it is not fully async.

doc/api/deprecations.md

@@ -2699,6 +2699,37 @@ resolutions not in `node_modules`. This means there will not be deprecation
 warnings for `"exports"` in dependencies. With `--pending-deprecation`, a
 runtime warning results no matter where the `"exports"` usage occurs.
 
+### DEP0147: `fs.readdir()`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: REPLACEME
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+[`fs.readdir()`][] is deprecated. Use [`fsPromises.opendir()`][] instead,
+where possible, otherwise use [`fs.opendir()`][].
+`fs.readdir()` is not fully asynchronous. It is asynchronous while gathering
+the list of directory entries but then sends them to JavaScript as one large
+array. In cases where this array contains hndreds of entries, particularly if
+`withFileTypes` is enabled, this can be quite slow and cause performance
+degredations.
+
+### DEP0148: `fs.readdirSync()`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: REPLACEME
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+[`fs.readdirSync()`][] is deprecated. Use [`fs.scandirSync()`][] instead.
+`fs.readdirSync()` was always mis-named.
+
 [Legacy URL API]: url.md#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -2750,9 +2781,14 @@ runtime warning results no matter where the `"exports"` usage occurs.
 [`fs.lchmodSync(path, mode)`]: fs.md#fs_fs_lchmodsync_path_mode
 [`fs.lchown(path, uid, gid, callback)`]: fs.md#fs_fs_lchown_path_uid_gid_callback
 [`fs.lchownSync(path, uid, gid)`]: fs.md#fs_fs_lchownsync_path_uid_gid
+[`fs.opendir()`]: fs.html#fs_fs_opendir_path_options_callback
 [`fs.read()`]: fs.md#fs_fs_read_fd_buffer_offset_length_position_callback
 [`fs.readSync()`]: fs.md#fs_fs_readsync_fd_buffer_offset_length_position
+[`fs.readdir()`]: fs.html#fs_fs_readdir_path_options_callback
+[`fs.readdirSync()`]: fs.html#fs_fs_readdirsync_path_options
+[`fs.scandirSync()`]: fs.html#fs_fs_scandirsync_path_options
 [`fs.stat()`]: fs.md#fs_fs_stat_path_options_callback
+[`fsPromises.opendir()`]: fs.html#fs_fspromises_opendir_path_options
 [`http.get()`]: http.md#http_http_get_options_callback
 [`http.request()`]: http.md#http_http_request_options_callback
 [`https.get()`]: https.md#https_https_get_options_callback

doc/api/fs.md

@@ -2957,6 +2957,7 @@ If no `options` object is specified, it will default with the above values.
 ## `fs.readdir(path[, options], callback)`
 <!-- YAML
 added: v0.1.8
+deprecated: REPLACEME
 changes:
   - version: v10.10.0
     pr-url: https://github.com/nodejs/node/pull/22020
@@ -2978,6 +2979,9 @@ changes:
     description: The `options` parameter was added.
 -->
 
+> Stability: 0 - Deprecated. Use [`fsPromises.opendir()`][] instead,
+where possible, otherwise use [`fs.opendir()`][].
+
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
@@ -2986,7 +2990,7 @@ changes:
   * `err` {Error}
   * `files` {string[]|Buffer[]|fs.Dirent[]}
 
-Asynchronous readdir(3). Reads the contents of a directory.
+Asynchronous scandir(3). Reads the contents of a directory.
 The callback gets two arguments `(err, files)` where `files` is an array of
 the names of the files in the directory excluding `'.'` and `'..'`.
 
@@ -3011,13 +3015,15 @@ changes:
                  protocol. Support is currently still *experimental*.
 -->
 
+> Stability: 0 - Deprecated. Use [`fs.scandirSync()`][] instead.
+
 * `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
   * `withFileTypes` {boolean} **Default:** `false`
 * Returns: {string[]|Buffer[]|fs.Dirent[]}
 
-Synchronous readdir(3).
+Synchronous scandir(3).
 
 The optional `options` argument can be a string specifying an encoding, or an
 object with an `encoding` property specifying the character encoding to use for
@@ -3654,6 +3660,27 @@ added: v14.14.0
 Synchronously removes files and directories (modeled on the standard POSIX `rm`
 utility). Returns `undefined`.
 
+## `fs.scandirSync(path[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {string|Object}
+  * `encoding` {string} **Default:** `'utf8'`
+  * `withFileTypes` {boolean} **Default:** `false`
+* Returns: {string[]|Buffer[]|fs.Dirent[]}
+
+Synchronous scandir(3).
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the filenames returned. If the `encoding` is set to `'buffer'`,
+the filenames returned will be passed as `Buffer` objects.
+
+If `options.withFileTypes` is set to `true`, the result will contain
+[`fs.Dirent`][] objects.
+
 ## `fs.stat(path[, options], callback)`
 <!-- YAML
 added: v0.0.2
@@ -6125,6 +6152,7 @@ the file contents.
 [`fs.readv()`]: #fs_fs_readv_fd_buffers_position_callback
 [`fs.realpath()`]: #fs_fs_realpath_path_options_callback
 [`fs.rmdir()`]: #fs_fs_rmdir_path_options_callback
+[`fs.scandirSync()`]: fs.html#fs_fs_scandirsync_path_options
 [`fs.stat()`]: #fs_fs_stat_path_options_callback
 [`fs.symlink()`]: #fs_fs_symlink_target_path_type_callback
 [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback