From b41989d03a38347a0ae018c5cbfbab898ba454fe Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Tue, 8 Oct 2019 13:18:08 -0700 Subject: doc: add more info to fs.Dir and fix typos Some doc bits / fixes which were missing from cbd8d715b2286e5726e6988921f5c870cbf74127 PR-URL: https://github.com/nodejs/node/pull/29890 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig Reviewed-By: Rich Trott Reviewed-By: Ruben Bridgewater Reviewed-By: Luigi Pinca Reviewed-By: James M Snell --- doc/api/fs.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/api/fs.md b/doc/api/fs.md index 885272724d..d7a4ebcc2e 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -293,8 +293,6 @@ A class representing a directory stream. Created by [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. -Example using async interation: - ```js const fs = require('fs'); @@ -356,13 +354,13 @@ Subsequent reads will result in errors. added: REPLACEME --> -* Returns: {Promise} containing {fs.Dirent} +* Returns: {Promise} containing {fs.Dirent|null} Asynchronously read the next directory entry via readdir(3) as an [`fs.Dirent`][]. -A `Promise` is returned that will be resolved with a [Dirent][] after the read -is completed. +After the read is completed, a `Promise` is returned that will be resolved with +an [`fs.Dirent`][], or `null` if there are no more directory entries to read. _Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms._ @@ -374,12 +372,13 @@ added: REPLACEME * `callback` {Function} * `err` {Error} - * `dirent` {fs.Dirent} + * `dirent` {fs.Dirent|null} Asynchronously read the next directory entry via readdir(3) as an [`fs.Dirent`][]. -The `callback` will be called with a [Dirent][] after the read is completed. +After the read is completed, the `callback` will be called with an +[`fs.Dirent`][], or `null` if there are no more directory entries to read. _Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms._ @@ -389,11 +388,13 @@ provided by the operating system's underlying directory mechanisms._ added: REPLACEME --> -* Returns: {fs.Dirent} +* Returns: {fs.Dirent|null} Synchronously read the next directory entry via readdir(3) as an [`fs.Dirent`][]. +If there are no more directory entries to read, `null` will be returned. + _Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms._ @@ -402,7 +403,15 @@ provided by the operating system's underlying directory mechanisms._ added: REPLACEME --> -* Returns: {AsyncIterator} to fully iterate over all entries in the directory. +* Returns: {AsyncIterator} of {fs.Dirent} + +Asynchronously iterates over the directory via readdir(3) until all entries have +been read. + +Entries returned by the async iterator are always an [`fs.Dirent`][]. +The `null` case from `dir.read()` is handled internally. + +See [`fs.Dir`][] for an example. _Directory entries returned by this iterator are in no particular order as provided by the operating system's underlying directory mechanisms._ @@ -4825,7 +4834,7 @@ and cleaning up the directory. The `encoding` option sets the encoding for the `path` while opening the directory and subsequent read operations. -Example using async interation: +Example using async iteration: ```js const fs = require('fs'); -- cgit v1.2.3