Add comment distinguishing Deno.Buffer from Node's Buffer (#4847)

1 files changed, 11 insertions, 0 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 0e44573fc..9f2c854d9 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -874,6 +874,17 @@ declare namespace Deno {
 
   /** A variable-sized buffer of bytes with `read()` and `write()` methods.
    *
+   * Deno.Buffer is almost always used with some I/O like files and sockets. It
+   * allows one to buffer up a download from a socket. Buffer grows and shrinks
+   * as necessary.
+   *
+   * Deno.Buffer is NOT the same thing as Node's Buffer. Node's Buffer was
+   * created in 2009 before JavaScript had the concept of ArrayBuffers. It's
+   * simply a non-standard ArrayBuffer.
+   *
+   * ArrayBuffer is a fixed memory allocation. Deno.Buffer is implemented on top
+   * of ArrayBuffer.
+   *
    * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer). */
   export class Buffer implements Reader, SyncReader, Writer, SyncWriter {
     constructor(ab?: ArrayBuffer);