doc: Update fs.read() documentation for clarity

[mertcanaltin]

This PR updates the documentation to clarify the behavior of Node.js's fs.read() method. It was noticed that there are ambiguities regarding the function of the length argument in the current documentation. The newly added explanations emphasize that the length argument specifies the maximum number of bytes to be read and that the actual number of bytes read may be less than this value. This update will help developers better understand and utilize the fs.read() method.

Issue #52447

[LiviaMedeiros]

It's described as fs.ftruncate(fd[, len], callback) in docs, which already means that fd and callback are mandatory. Would you like to elaborate why this is needed?
Also, the linked issue doesn't look related.

[mertcanaltin]

It's described as fs.ftruncate(fd[, len], callback) in docs, which already means that fd and callback are mandatory. Would you like to elaborate why this is needed? Also, the linked issue doesn't look related.

Yes, I misunderstood, I tried to read better and make a document (I commented that we should specify the callback parameter)

[mertcanaltin]

I did an update and I wonder if I'm on the right track @LiviaMedeiros

[mcollina]

lgtm

[mcollina]

lgtm

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/52453
✔  Done loading data for nodejs/node/pull/52453
----------------------------------- PR info ------------------------------------
Title      doc: Update fs.read() documentation for clarity (#52453)
Author     Mert Can Altin  (@mertcanaltin)
Branch     mertcanaltin:dev-52447 -> nodejs:main
Labels     doc, fs, commit-queue-squash
Commits    8
 - doc: update fs.read() documentation for clarity
 - Update fs.md
 - update fs.read() documentation with clarification on EOF handling
 - Merge branch 'dev-52447' of https://github.com/mertcanaltin/node into…
 - unnecessary space removed
 - fix: statements organized
 - fix: statements organized
 - docs: Update fs.read() documentation for clarity
Committers 2
 - Mert Can Altin 
 - GitHub 
PR-URL: https://github.com/nodejs/node/pull/52453
Reviewed-By: Matteo Collina 
Reviewed-By: Marco Ippolito 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/52453
Reviewed-By: Matteo Collina 
Reviewed-By: Marco Ippolito 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Wed, 10 Apr 2024 18:50:23 GMT
   ✔  Approvals: 2
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/52453#pullrequestreview-2020283381
   ✔  - Marco Ippolito (@marco-ippolito): https://github.com/nodejs/node/pull/52453#pullrequestreview-1999533582
   ⚠  GitHub cannot link the author of 'doc: update fs.read() documentation for clarity' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'update fs.read() documentation with clarification on EOF handling' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'Merge branch 'dev-52447' of https://github.com/mertcanaltin/node into…' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'unnecessary space removed' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'fix: statements organized' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'fix: statements organized' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ⚠  GitHub cannot link the author of 'docs: Update fs.read() documentation for clarity' to their GitHub account.
   ⚠  Please suggest them to take a look at https://github.com/nodejs/node/blob/99b1ada/doc/guides/contributing/pull-requests.md#step-1-fork
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 52453
From https://github.com/nodejs/node
 * branch                  refs/pull/52453/merge -> FETCH_HEAD
✔  Fetched commits as ac9aa37bcb5e..83886ed9062f
--------------------------------------------------------------------------------
[main 5331638bd1] doc: update fs.read() documentation for clarity
 Author: Mert Can Altin 
 Date: Thu Apr 11 10:54:23 2024 +0300
 1 file changed, 26 insertions(+)
[main 6833765805] Update fs.md
 Author: Mert Can Altin 
 Date: Thu Apr 11 11:34:06 2024 +0300
 1 file changed, 1 insertion(+), 1 deletion(-)
Auto-merging doc/api/fs.md
error: commit ca223a3f1d636b1bcbc0ea5fed6c0bca3f82ccca is a merge but no -m option was given.
fatal: cherry-pick failed
[main da4e265036] update fs.read() documentation with clarification on EOF handling
 Author: Mert Can Altin 
 Date: Sun Apr 14 14:59:44 2024 +0300
 1 file changed, 3 insertions(+), 1 deletion(-)
   ✘  Failed to apply patches

https://github.com/nodejs/node/actions/runs/8819523502

[LiviaMedeiros]

This is unrelated to fs.ftruncate() and must be moved to fs.read() part of documentation before merging.

[mertcanaltin]

This is unrelated to fs.ftruncate() and must be moved to fs.read() part of documentation before merging.

do you have a chance to send a change proposal I'm a little confused @LiviaMedeiros

[LiviaMedeiros]

fs.read(fd, buffer, offset, length, position, callback) (where the change belongs) is there. This is fs.ftruncate(fd[, len], callback).

[mertcanaltin]

fs.read(fd, buffer, offset, length, position, callback) (where the change belongs) is there. This is fs.ftruncate(fd[, len], callback).

I updated as you said thank you very much ❤️ 🙏

resolved

[nodejs-github-bot]

Landed in a27f473