From dfb19a4decc01790dee98a63a29640850b1103c7 Mon Sep 17 00:00:00 2001
From: Chxxeton <43923165+Chxxeton@users.noreply.github.com>
Date: Sat, 15 Aug 2026 08:42:59 -0400
Subject: [PATCH] doc: add missing return types in fs.md

Three entries in the fs documentation described their return
value only in prose, or not at all, so doc-kit could not parse
a return type and fell back to `void`:

* `filehandle[Symbol.asyncDispose]()` and
  `dir[Symbol.asyncDispose]()` both return a promise, matching
  the existing `Returns: {Promise}` annotations on other async
  dispose methods.
* `new fs.Utf8Stream([options])` is a constructor and returns
  an instance of the class.

Verified at runtime and by rendering the page locally with
doc-kit.

Refs: https://github.com/nodejs/doc-kit/issues/953
Signed-off-by: Chxxeton <43923165+Chxxeton@users.noreply.github.com>
---
 doc/api/fs.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 21eaa6af0e1c..35960f15172e 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1191,6 +1191,8 @@ changes:
    description: No longer experimental.
 -->
 
+* Returns: {Promise}
+
 Calls `filehandle.close()` and returns a promise that fulfills when the
 filehandle is closed.
 
@@ -7348,6 +7350,8 @@ changes:
    description: No longer experimental.
 -->
 
+* Returns: {Promise}
+
 Calls `dir.close()` if the directory handle is open, and returns a promise that
 fulfills when disposal is complete.
 
@@ -8413,6 +8417,7 @@ of bytes written is passed as the first argument to the event handler.
     * `writeBufferLen` {number}
     * `remainingBufferLen`: {number}
   * `sync`: {boolean} Perform writes synchronously.
+* Returns: {fs.Utf8Stream}
 
 #### `utf8Stream.append`