doc: clarify and warn on Deno.read/write behaviour (#5743)

1 files changed, 22 insertions, 2 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index f5e9c0fe7..d2a18c414 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -456,6 +456,11 @@ declare namespace Deno {
    * It is possible for a read to successfully return with `0` bytes. This does
    * not indicate EOF.
    *
+   * This function is one of the lowest level APIs and most users should not
+   * work with this directly, but rather use Deno.readAllSync() instead.
+   *
+   * **It is not guaranteed that the full buffer will be read in a single call.**
+   *
    * ```ts
    * // if "/foo/bar.txt" contains the text "hello world":
    * const file = Deno.openSync("/foo/bar.txt");
@@ -475,6 +480,11 @@ declare namespace Deno {
    * It is possible for a read to successfully return with `0` bytes. This does
    * not indicate EOF.
    *
+   * This function is one of the lowest level APIs and most users should not
+   * work with this directly, but rather use Deno.readAll() instead.
+   *
+   * **It is not guaranteed that the full buffer will be read in a single call.**
+   *
    * ```ts
    * // if "/foo/bar.txt" contains the text "hello world":
    * const file = await Deno.open("/foo/bar.txt");
@@ -489,7 +499,12 @@ declare namespace Deno {
   /** Synchronously write to the resource ID (`rid`) the contents of the array
    * buffer (`data`).
    *
-   * Returns the number of bytes written.
+   * Returns the number of bytes written.  This function is one of the lowest
+   * level APIs and most users should not work with this directly, but rather use
+   * Deno.writeAllSync() instead.
+   *
+   * **It is not guaranteed that the full buffer will be written in a single
+   * call.**
    *
    * ```ts
    * const encoder = new TextEncoder();
@@ -503,7 +518,12 @@ declare namespace Deno {
 
   /** Write to the resource ID (`rid`) the contents of the array buffer (`data`).
    *
-   * Resolves to the number of bytes written.
+   * Resolves to the number of bytes written.  This function is one of the lowest
+   * level APIs and most users should not work with this directly, but rather use
+   * Deno.writeAll() instead.
+   *
+   * **It is not guaranteed that the full buffer will be written in a single
+   * call.**
    *
    * ```ts
    * const encoder = new TextEncoder();