diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 0e44573fc9..9f2c854d9c 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -873,6 +873,17 @@ declare namespace Deno {
   export function setRaw(rid: number, mode: boolean): void;
 
   /** 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 {