Add comment distinguishing Deno.Buffer from Node's Buffer
@@ -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 {
