From 5a842a5d9c7ca3abfb7bc88352002411f1321075 Mon Sep 17 00:00:00 2001
From: RoomWithOutRoof <RoomWithOutRoof@users.noreply.github.com>
Date: Sat, 18 Apr 2026 00:29:17 +0800
Subject: [PATCH] doc: improve fs.StatFs documentation

- Clarify that bsize is in bytes (not bits)
- Add examples for calculating available/free/total space
- Improve files description to mention inodes
- Add explanation for type field with examples

Fixes: https://github.com/nodejs/node/issues/50749
---
 doc/api/fs.md | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 94aea1032f539c..0779db5b7af2de 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7938,6 +7938,16 @@ added:
 
 Free blocks available to unprivileged users.
 
+Example using `bsize` and `bavail` to calculate available space in bytes:
+
+```js
+import { statfs } from "fs/promises";
+
+const stats = await statfs("/tmp");
+const availableBytes = stats.bsize * stats.bavail;
+console.log(`Available space: ${availableBytes} bytes`);
+```
+
 #### `statfs.bfree`
 
 <!-- YAML
@@ -7950,6 +7960,16 @@ added:
 
 Free blocks in file system.
 
+Example using `bsize` and `bfree` to calculate total free space in bytes:
+
+```js
+import { statfs } from "fs/promises";
+
+const stats = await statfs("/tmp");
+const freeBytes = stats.bsize * stats.bfree;
+console.log(`Free space: ${freeBytes} bytes`);
+```
+
 #### `statfs.blocks`
 
 <!-- YAML
@@ -7962,6 +7982,16 @@ added:
 
 Total data blocks in file system.
 
+Example using `bsize` and `blocks` to calculate total file system size in bytes:
+
+```js
+import { statfs } from "fs/promises";
+
+const stats = await statfs("/tmp");
+const totalBytes = stats.bsize * stats.blocks;
+console.log(`Total size: ${totalBytes} bytes`);
+```
+
 #### `statfs.bsize`
 
 <!-- YAML
@@ -7972,7 +8002,7 @@ added:
 
 * Type: {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size, in **bytes**.
 
 #### `statfs.frsize`
 
@@ -8006,7 +8036,7 @@ added:
 
 * Type: {number|bigint}
 
-Total file nodes in file system.
+Total file nodes (inodes) in file system.
 
 #### `statfs.type`
 
@@ -8018,7 +8048,10 @@ added:
 
 * Type: {number|bigint}
 
-Type of file system.
+File system type identifier. The value corresponds to the `f_type` field
+from the underlying `statfs` system call (e.g., `0x1021994` for `ext2`,
+`0x4d44` for `vfat`). Platform-specific constants like `FStype.EXT2`
+may be used for comparison when available.
 
 ### Class: `fs.Utf8Stream`