From 849f5300a7aa5cac54ef2abf6e35e6e961e89d52 Mon Sep 17 00:00:00 2001
From: AliMahmoudDev <123aliactionx5@gmail.com>
Date: Sun, 24 May 2026 20:55:29 +0000
Subject: [PATCH] doc: improve fs.StatFs property documentation

Fixes #50749

- statfs.bsize: clarify the unit is bytes (not bits)
- statfs.bavail: add example showing how to calculate available
  size in bytes (bsize * bavail)
- statfs.bfree: add example showing how to calculate free size
  in bytes (bsize * bfree)
- statfs.type: explain that it is a numeric filesystem identifier
  and provide common examples (ext4, FAT)
---
 doc/api/fs.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 8c20afd92182de..db8a5f707cb1eb 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -8002,7 +8002,8 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks available to unprivileged users.
+Free blocks available to unprivileged users. Multiply by `statfs.bsize` to get
+the available size in bytes: `statfs.bsize * statfs.bavail`.
 
 #### `statfs.bfree`
 
@@ -8014,7 +8015,8 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks in file system.
+Free blocks in the file system. Multiply by `statfs.bsize` to get
+the free size in bytes: `statfs.bsize * statfs.bfree`.
 
 #### `statfs.blocks`
 
@@ -8038,7 +8040,8 @@ added:
 
 * Type: {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size **in bytes**. Multiply this by block counts
+(e.g., `statfs.bavail` or `statfs.bfree`) to calculate sizes in bytes.
 
 #### `statfs.frsize`
 
@@ -8086,7 +8089,10 @@ added:
 
 * Type: {number|bigint}
 
-Type of file system.
+Type of file system. The value is a numeric identifier corresponding to the
+file system type (e.g., `0xEF53` for ext4, `0x4D44` for FAT). These values
+are platform-specific and derived from the `f_type` field of `statvfs`/`statfs`
+on POSIX systems, or equivalent platform APIs.
 
 ### Class: `fs.Utf8Stream`