doc: clarify and warn on Deno.read/write behaviour
@@ -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();
