From 8a3e314ef269cc35801f68fcc01620b1c5669827 Mon Sep 17 00:00:00 2001
From: Spotandjake <spotandjake@hotmail.com>
Date: Mon, 1 Jan 2024 21:46:35 -0500
Subject: [PATCH] chore(stdlib): Add examples to buffer library

---
 stdlib/buffer.gr | 259 ++++++++++++++++++++++++++++++
 stdlib/buffer.md | 408 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 667 insertions(+)

diff --git a/stdlib/buffer.gr b/stdlib/buffer.gr
index 1700b56401..92ae4c0f68 100644
--- a/stdlib/buffer.gr
+++ b/stdlib/buffer.gr
@@ -2,8 +2,11 @@
  * Utilities for working with buffers.
  *
  * Buffers are data structures that automatically expand as more data is appended. They are useful for storing and operating on an unknown number of bytes. All set or append operations mutate the buffer.
+ *
  * @example include "buffer"
  *
+ * @example Buffer.make(64)
+ *
  * @since v0.4.0
  */
 
@@ -136,6 +139,9 @@ let addUint32help = (value, buffer) => {
  *
  * @throws InvalidArgument(String): When the `initialSize` is a negative number
  *
+ * @example Buffer.make(0)
+ * @example Buffer.make(64)
+ *
  * @since v0.4.0
  */
 provide let make = initialSize => {
@@ -150,6 +156,12 @@ provide let make = initialSize => {
  * @param buffer: The buffer to access
  * @returns The length of the buffer in bytes
  *
+ * @example Buffer.length(Buffer.make(32)) == 0
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.length(buf) == 4
+ *
  * @since v0.4.0
  */
 provide let length = buffer => buffer.len
@@ -161,6 +173,13 @@ provide let length = buffer => buffer.len
  *
  * @param buffer: The buffer to clear
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.length(buf) == 4
+ * Buffer.clear(buf)
+ * assert Buffer.length(buf) == 0
+ *
  * @since v0.4.0
  */
 provide let clear = buffer => {
@@ -175,6 +194,13 @@ provide let clear = buffer => {
  *
  * @param buffer: The buffer to reset
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.length(buf) == 4
+ * Buffer.reset(buf)
+ * assert Buffer.length(buf) == 0
+ *
  * @since v0.4.0
  */
 provide let reset = buffer => {
@@ -193,6 +219,13 @@ provide let reset = buffer => {
  * @throws IndexOutOfBounds: When the `length` is negative
  * @throws IndexOutOfBounds: When the `length` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.length(buf) == 4
+ * Buffer.truncate(1, buf)
+ * assert Buffer.length(buf) == 1
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -213,6 +246,11 @@ provide let truncate = (length, buffer) => {
  * @param buffer: The buffer to copy into a byte sequence
  * @returns A byte sequence made from copied buffer data
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addString("test", buf)
+ * assert Buffer.toBytes(buf) == b"test"
+ *
  * @since v0.4.0
  */
 provide let toBytes = buffer => {
@@ -231,6 +269,11 @@ provide let toBytes = buffer => {
  * @throws IndexOutOfBounds: When `start` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `start + length` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addString("HelloWorld", buf)
+ * assert Buffer.toBytesSlice(0, 5, buf) == b"Hello"
+ *
  * @since v0.4.0
  */
 provide let toBytesSlice = (start, length, buffer) => {
@@ -244,6 +287,11 @@ provide let toBytesSlice = (start, length, buffer) => {
  * @param buffer: The buffer to stringify
  * @returns A string made with data copied from the buffer
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addString("HelloWorld", buf)
+ * assert Buffer.toString(buf) == "HelloWorld"
+ *
  * @since v0.4.0
  */
 provide let toString = buffer => {
@@ -258,6 +306,11 @@ provide let toString = buffer => {
  * @param buffer: The buffer to copy from
  * @returns A string made with a subset of data copied from the buffer
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addString("HelloWorld", buf)
+ * assert Buffer.toStringSlice(0, 5, buf) == "Hello"
+ *
  * @since v0.4.0
  */
 provide let toStringSlice = (start, length, buffer) => {
@@ -270,6 +323,11 @@ provide let toStringSlice = (start, length, buffer) => {
  * @param bytes: The byte sequence to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addBytes(b"test", buf)
+ * assert Buffer.toBytes(buf) == b"test"
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -293,6 +351,11 @@ provide let addBytes = (bytes, buffer) => {
  * @param string: The string to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addString("Hello", buf)
+ * assert Buffer.toString(buf) == "Hello"
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -316,6 +379,11 @@ provide let addString = (string, buffer) => {
  * @param char: The character to append to the buffer
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addChar('H', buf)
+ * assert Buffer.toString(buf) == "H"
+ *
  * @since v0.4.0
  */
 provide let addChar = (char, buffer) => {
@@ -328,6 +396,11 @@ provide let addChar = (char, buffer) => {
  * @param codePoint: The code point to append to the buffer
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addCharFromCodePoint(72, buf)
+ * assert Buffer.toString(buf) == "H"
+ *
  * @since v0.6.0
  */
 provide let addCharFromCodePoint = (codePoint: Number, buffer) => {
@@ -342,6 +415,11 @@ provide let addCharFromCodePoint = (codePoint: Number, buffer) => {
  * @param string: The string to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addStringSlice(0, 5, "HelloWorld", buf)
+ * assert Buffer.toString(buf) == "Hello"
+ *
  * @since v0.4.0
  * @history v0.5.0: Now takes the end offset instead of length
  */
@@ -375,6 +453,11 @@ provide let addStringSlice = (start: Number, end, string, buffer) => {
  * @throws IndexOutOfBounds: When the `length` is negative
  * @throws IndexOutOfBounds: When the `length` is greater than the `bytes` length minus `start`
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addBytesSlice(0, 5, b"HelloWorld", buf)
+ * assert Buffer.toString(buf) == "Hello"
+ *
  * @since v0.4.0
  */
 @unsafe
@@ -420,6 +503,14 @@ provide let addBytesSlice =
  * @param srcBuffer: The buffer to append
  * @param dstBuffer: The buffer to mutate
  *
+ * @example
+ * let buf1 = Buffer.make(0)
+ * Buffer.addString("Hello", buf1)
+ * let buf2 = Buffer.make(0)
+ * Buffer.addString("World", buf2)
+ * Buffer.addBuffer(buf2, buf1)
+ * assert Buffer.toString(buf1) == "HelloWorld"
+ *
  * @since v0.4.0
  */
 provide let addBuffer = (srcBuffer, dstBuffer) => {
@@ -436,6 +527,14 @@ provide let addBuffer = (srcBuffer, dstBuffer) => {
  * @param srcBuffer: The buffer to append
  * @param dstBuffer: The buffer to mutate
  *
+ * @example
+ * let buf1 = Buffer.make(0)
+ * Buffer.addString("Hello", buf1)
+ * let buf2 = Buffer.make(0)
+ * Buffer.addString("HiWorld", buf2)
+ * Buffer.addBufferSlice(2, 5, buf2, buf1)
+ * assert Buffer.toString(buf1) == "HelloWorld"
+ *
  * @since v0.4.0
  */
 provide let addBufferSlice = (start, length, srcBuffer, dstBuffer) => {
@@ -453,6 +552,11 @@ provide let addBufferSlice = (start, length, srcBuffer, dstBuffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt8(1s, buf)
+ * assert Buffer.getInt8(0, buf) == 1s
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally called `getInt8S`, returning an `Int32`
  */
@@ -472,6 +576,12 @@ provide let getInt8 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setInt8(0, 3s, buf)
+ * assert Buffer.getInt8(0, buf) == 3s
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int8`
  */
@@ -486,6 +596,11 @@ provide let setInt8 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt8(2s, buf)
+ * assert Buffer.getInt8(0, buf) == 2s
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int8`
  */
@@ -504,6 +619,11 @@ provide let addInt8 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint8(3us, buf)
+ * assert Buffer.getUint8(0, buf) == 3us
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally called `getInt8U`, returning an `Int32`
  */
@@ -523,6 +643,12 @@ provide let getUint8 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 1` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setUint8(4us, buf)
+ * assert Buffer.getUint8(0, buf) == 4us
+ *
  * @since v0.6.0
  */
 provide let setUint8 = (index, value, buffer) => {
@@ -536,6 +662,11 @@ provide let setUint8 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint8(0us, buf)
+ * assert Buffer.getUint8(0, buf) == 0us
+ *
  * @since v0.6.0
  */
 provide let addUint8 = (value, buffer) => {
@@ -553,6 +684,11 @@ provide let addUint8 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addInt16(1S, buf)
+ * assert Buffer.getInt16(0, buf) == 1S
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally called `getInt16S`, returning an `Int32`
  */
@@ -572,6 +708,12 @@ provide let getInt16 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setInt16(5, 1S, buf)
+ * assert Buffer.getInt16(5, buf) == 1S
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int16`
  */
@@ -586,6 +728,11 @@ provide let setInt16 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt16(2S, buf)
+ * assert Buffer.getInt16(0, buf) == 2S
+ *
  * @since v0.4.0
  * @history v0.6.0: `value` argument type changed to `Int16`
  */
@@ -604,6 +751,11 @@ provide let addInt16 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addUint16(1uS, buf)
+ * assert Buffer.getUint16(0, buf) == 1uS
+ *
  * @since v0.6.0
  * @history v0.4.0: Originally called `getInt16U`, returning an `Int32`
  */
@@ -623,6 +775,12 @@ provide let getUint16 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 2` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setUint16(0, 1uS, buf)
+ * assert Buffer.getUint16(0, buf) == 1uS
+ *
  * @since v0.6.0
  */
 provide let setUint16 = (index, value, buffer) => {
@@ -636,6 +794,11 @@ provide let setUint16 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addUint16(0, 2uS, buf)
+ * assert Buffer.getUint16(0, buf) == 2uS
+ *
  * @since v0.6.0
  */
 provide let addUint16 = (value, buffer) => {
@@ -653,6 +816,11 @@ provide let addUint16 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(0)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.getInt32(0, buf) == 1l
+ *
  * @since v0.4.0
  */
 provide let getInt32 = (index, buffer) => {
@@ -671,6 +839,12 @@ provide let getInt32 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(64)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setInt32(3, 1l, buf)
+ * assert Buffer.getInt32(3, buf) == 1l
+ *
  * @since v0.4.0
  */
 provide let setInt32 = (index, value, buffer) => {
@@ -684,6 +858,11 @@ provide let setInt32 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(64)
+ * Buffer.addInt32(1l, buf)
+ * assert Buffer.getInt32(0, buf) == 1l
+ *
  * @since v0.4.0
  */
 provide let addInt32 = (value, buffer) => {
@@ -701,6 +880,11 @@ provide let addInt32 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint32(1ul, buf)
+ * assert Buffer.getUint32(0, buf) == 1ul
+ *
  * @since v0.6.0
  */
 provide let getUint32 = (index, buffer) => {
@@ -719,6 +903,12 @@ provide let getUint32 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setUint32(0, 1ul, buf)
+ * assert Buffer.getUint32(0, buf) == 1ul
+ *
  * @since v0.6.0
  */
 provide let setUint32 = (index, value, buffer) => {
@@ -732,6 +922,11 @@ provide let setUint32 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint32(1ul, buf)
+ * assert Buffer.getUint32(0, buf) == 1ul
+ *
  * @since v0.6.0
  */
 provide let addUint32 = (value, buffer) => {
@@ -749,6 +944,11 @@ provide let addUint32 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addFloat32(1.0f, buf)
+ * assert Buffer.getFloat32(0, buf) == 1.0f
+ *
  * @since v0.4.0
  */
 provide let getFloat32 = (index, buffer) => {
@@ -767,6 +967,12 @@ provide let getFloat32 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 4` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setFloat32(0, 1.0f, buf)
+ * assert Buffer.getFloat32(0, buf) == 1.0f
+ *
  * @since v0.4.0
  */
 provide let setFloat32 = (index, value, buffer) => {
@@ -780,6 +986,11 @@ provide let setFloat32 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addFloat32(1.0f, buf)
+ * assert Buffer.getFloat32(0, buf) == 1.0f
+ *
  * @since v0.4.0
  */
 provide let addFloat32 = (value, buffer) => {
@@ -800,6 +1011,11 @@ provide let addFloat32 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addInt64(1L, buf)
+ * assert Buffer.getInt64(0, buf) == 1L
+ *
  * @since v0.4.0
  */
 provide let getInt64 = (index, buffer) => {
@@ -818,6 +1034,12 @@ provide let getInt64 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setInt64(0, 1L, buf)
+ * assert Buffer.getInt64(0, buf) == 1L
+ *
  * @since v0.4.0
  */
 provide let setInt64 = (index, value, buffer) => {
@@ -831,6 +1053,11 @@ provide let setInt64 = (index, value, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addInt64(1L, buf)
+ * assert Buffer.getInt64(0, buf) == 1L
+ *
  * @since v0.4.0
  */
 provide let addInt64 = (value, buffer) => {
@@ -851,6 +1078,11 @@ provide let addInt64 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint64(1uL, buf)
+ * assert Buffer.getUint64(0, buf) == 1uL
+ *
  * @since v0.6.0
  */
 provide let getUint64 = (index, buffer) => {
@@ -869,6 +1101,12 @@ provide let getUint64 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setUint64(0, 1uL, buf)
+ * assert Buffer.getUint64(0, buf) == 1uL
+ *
  * @since v0.6.0
  */
 provide let setUint64 = (index, value, buffer) => {
@@ -882,6 +1120,11 @@ provide let setUint64 = (index, value, buffer) => {
  * @param value: The value to set
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addUint64(1uL, buf)
+ * assert Buffer.getUint64(0, buf) == 1uL
+ *
  * @since v0.6.0
  */
 provide let addUint64 = (value, buffer) => {
@@ -902,6 +1145,11 @@ provide let addUint64 = (value, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addFloat64(1.0F, buf)
+ * assert Buffer.getFloat64(0, buf) == 1.0F
+ *
  * @since v0.4.0
  */
 provide let getFloat64 = (index, buffer) => {
@@ -920,6 +1168,12 @@ provide let getFloat64 = (index, buffer) => {
  * @throws IndexOutOfBounds: When `index` is greater than or equal to the buffer size
  * @throws IndexOutOfBounds: When `index + 8` is greater than the buffer size
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addString("Hello World", buf)
+ * Buffer.setFloat64(0, 1.0F, buf)
+ * assert Buffer.getFloat64(0, buf) == 1.0F
+ *
  * @since v0.4.0
  */
 provide let setFloat64 = (index, value, buffer) => {
@@ -933,6 +1187,11 @@ provide let setFloat64 = (index, value, buffer) => {
  * @param value: The value to append
  * @param buffer: The buffer to mutate
  *
+ * @example
+ * let buf = Buffer.make(32)
+ * Buffer.addFloat64(1.0F, buf)
+ * assert Buffer.getFloat64(0, buf) == 1.0F
+ *
  * @since v0.4.0
  */
 provide let addFloat64 = (value, buffer) => {
diff --git a/stdlib/buffer.md b/stdlib/buffer.md
index 8dbb2433a7..98364bf0d2 100644
--- a/stdlib/buffer.md
+++ b/stdlib/buffer.md
@@ -15,6 +15,10 @@ No other changes yet.
 include "buffer"
 ```
 
+```grain
+Buffer.make(64)
+```
+
 ## Types
 
 Type declarations included in the Buffer module.
@@ -63,6 +67,16 @@ Throws:
 
 * When the `initialSize` is a negative number
 
+Examples:
+
+```grain
+Buffer.make(0)
+```
+
+```grain
+Buffer.make(64)
+```
+
 ### Buffer.**length**
 
 <details disabled>
@@ -88,6 +102,18 @@ Returns:
 |----|-----------|
 |`Number`|The length of the buffer in bytes|
 
+Examples:
+
+```grain
+Buffer.length(Buffer.make(32)) == 0
+```
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addInt32(1l, buf)
+assert Buffer.length(buf) == 4
+```
+
 ### Buffer.**clear**
 
 <details disabled>
@@ -109,6 +135,16 @@ Parameters:
 |-----|----|-----------|
 |`buffer`|`Buffer`|The buffer to clear|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt32(1l, buf)
+assert Buffer.length(buf) == 4
+Buffer.clear(buf)
+assert Buffer.length(buf) == 0
+```
+
 ### Buffer.**reset**
 
 <details disabled>
@@ -130,6 +166,16 @@ Parameters:
 |-----|----|-----------|
 |`buffer`|`Buffer`|The buffer to reset|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt32(1l, buf)
+assert Buffer.length(buf) == 4
+Buffer.reset(buf)
+assert Buffer.length(buf) == 0
+```
+
 ### Buffer.**truncate**
 
 <details disabled>
@@ -159,6 +205,16 @@ Throws:
 * When the `length` is negative
 * When the `length` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt32(1l, buf)
+assert Buffer.length(buf) == 4
+Buffer.truncate(1, buf)
+assert Buffer.length(buf) == 1
+```
+
 ### Buffer.**toBytes**
 
 <details disabled>
@@ -184,6 +240,14 @@ Returns:
 |----|-----------|
 |`Bytes`|A byte sequence made from copied buffer data|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addString("test", buf)
+assert Buffer.toBytes(buf) == b"test"
+```
+
 ### Buffer.**toBytesSlice**
 
 <details disabled>
@@ -219,6 +283,14 @@ Throws:
 * When `start` is greater than or equal to the buffer size
 * When `start + length` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addString("HelloWorld", buf)
+assert Buffer.toBytesSlice(0, 5, buf) == b"Hello"
+```
+
 ### Buffer.**toString**
 
 <details disabled>
@@ -244,6 +316,14 @@ Returns:
 |----|-----------|
 |`String`|A string made with data copied from the buffer|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addString("HelloWorld", buf)
+assert Buffer.toString(buf) == "HelloWorld"
+```
+
 ### Buffer.**toStringSlice**
 
 <details disabled>
@@ -271,6 +351,14 @@ Returns:
 |----|-----------|
 |`String`|A string made with a subset of data copied from the buffer|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addString("HelloWorld", buf)
+assert Buffer.toStringSlice(0, 5, buf) == "Hello"
+```
+
 ### Buffer.**addBytes**
 
 <details disabled>
@@ -291,6 +379,14 @@ Parameters:
 |`bytes`|`Bytes`|The byte sequence to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addBytes(b"test", buf)
+assert Buffer.toBytes(buf) == b"test"
+```
+
 ### Buffer.**addString**
 
 <details disabled>
@@ -311,6 +407,14 @@ Parameters:
 |`string`|`String`|The string to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addString("Hello", buf)
+assert Buffer.toString(buf) == "Hello"
+```
+
 ### Buffer.**addChar**
 
 <details disabled>
@@ -331,6 +435,14 @@ Parameters:
 |`char`|`Char`|The character to append to the buffer|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addChar('H', buf)
+assert Buffer.toString(buf) == "H"
+```
+
 ### Buffer.**addCharFromCodePoint**
 
 <details disabled>
@@ -351,6 +463,14 @@ Parameters:
 |`codePoint`|`Number`|The code point to append to the buffer|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addCharFromCodePoint(72, buf)
+assert Buffer.toString(buf) == "H"
+```
+
 ### Buffer.**addStringSlice**
 
 <details>
@@ -381,6 +501,14 @@ Parameters:
 |`string`|`String`|The string to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addStringSlice(0, 5, "HelloWorld", buf)
+assert Buffer.toString(buf) == "Hello"
+```
+
 ### Buffer.**addBytesSlice**
 
 <details disabled>
@@ -413,6 +541,14 @@ Throws:
 * When the `length` is negative
 * When the `length` is greater than the `bytes` length minus `start`
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addBytesSlice(0, 5, b"HelloWorld", buf)
+assert Buffer.toString(buf) == "Hello"
+```
+
 ### Buffer.**addBuffer**
 
 <details disabled>
@@ -435,6 +571,17 @@ Parameters:
 |`srcBuffer`|`Buffer`|The buffer to append|
 |`dstBuffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf1 = Buffer.make(0)
+Buffer.addString("Hello", buf1)
+let buf2 = Buffer.make(0)
+Buffer.addString("World", buf2)
+Buffer.addBuffer(buf2, buf1)
+assert Buffer.toString(buf1) == "HelloWorld"
+```
+
 ### Buffer.**addBufferSlice**
 
 <details disabled>
@@ -461,6 +608,17 @@ Parameters:
 |`srcBuffer`|`Buffer`|The buffer to append|
 |`dstBuffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf1 = Buffer.make(0)
+Buffer.addString("Hello", buf1)
+let buf2 = Buffer.make(0)
+Buffer.addString("HiWorld", buf2)
+Buffer.addBufferSlice(2, 5, buf2, buf1)
+assert Buffer.toString(buf1) == "HelloWorld"
+```
+
 ### Buffer.**getInt8**
 
 <details>
@@ -502,6 +660,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 1` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt8(1s, buf)
+assert Buffer.getInt8(0, buf) == 1s
+```
+
 ### Buffer.**setInt8**
 
 <details>
@@ -538,6 +704,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 1` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setInt8(0, 3s, buf)
+assert Buffer.getInt8(0, buf) == 3s
+```
+
 ### Buffer.**addInt8**
 
 <details>
@@ -565,6 +740,14 @@ Parameters:
 |`value`|`Int8`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt8(2s, buf)
+assert Buffer.getInt8(0, buf) == 2s
+```
+
 ### Buffer.**getUint8**
 
 <details>
@@ -606,6 +789,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 1` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint8(3us, buf)
+assert Buffer.getUint8(0, buf) == 3us
+```
+
 ### Buffer.**setUint8**
 
 <details disabled>
@@ -635,6 +826,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 1` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setUint8(4us, buf)
+assert Buffer.getUint8(0, buf) == 4us
+```
+
 ### Buffer.**addUint8**
 
 <details disabled>
@@ -655,6 +855,14 @@ Parameters:
 |`value`|`Uint8`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint8(0us, buf)
+assert Buffer.getUint8(0, buf) == 0us
+```
+
 ### Buffer.**getInt16**
 
 <details>
@@ -696,6 +904,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 2` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addInt16(1S, buf)
+assert Buffer.getInt16(0, buf) == 1S
+```
+
 ### Buffer.**setInt16**
 
 <details>
@@ -732,6 +948,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 2` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setInt16(5, 1S, buf)
+assert Buffer.getInt16(5, buf) == 1S
+```
+
 ### Buffer.**addInt16**
 
 <details>
@@ -759,6 +984,14 @@ Parameters:
 |`value`|`Int16`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt16(2S, buf)
+assert Buffer.getInt16(0, buf) == 2S
+```
+
 ### Buffer.**getUint16**
 
 <details>
@@ -800,6 +1033,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 2` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addUint16(1uS, buf)
+assert Buffer.getUint16(0, buf) == 1uS
+```
+
 ### Buffer.**setUint16**
 
 <details disabled>
@@ -829,6 +1070,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 2` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setUint16(0, 1uS, buf)
+assert Buffer.getUint16(0, buf) == 1uS
+```
+
 ### Buffer.**addUint16**
 
 <details disabled>
@@ -849,6 +1099,14 @@ Parameters:
 |`value`|`Uint16`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addUint16(0, 2uS, buf)
+assert Buffer.getUint16(0, buf) == 2uS
+```
+
 ### Buffer.**getInt32**
 
 <details disabled>
@@ -883,6 +1141,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(0)
+Buffer.addInt32(1l, buf)
+assert Buffer.getInt32(0, buf) == 1l
+```
+
 ### Buffer.**setInt32**
 
 <details disabled>
@@ -912,6 +1178,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(64)
+Buffer.addString("Hello World", buf)
+Buffer.setInt32(3, 1l, buf)
+assert Buffer.getInt32(3, buf) == 1l
+```
+
 ### Buffer.**addInt32**
 
 <details disabled>
@@ -932,6 +1207,14 @@ Parameters:
 |`value`|`Int32`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(64)
+Buffer.addInt32(1l, buf)
+assert Buffer.getInt32(0, buf) == 1l
+```
+
 ### Buffer.**getUint32**
 
 <details disabled>
@@ -966,6 +1249,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint32(1ul, buf)
+assert Buffer.getUint32(0, buf) == 1ul
+```
+
 ### Buffer.**setUint32**
 
 <details disabled>
@@ -995,6 +1286,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setUint32(0, 1ul, buf)
+assert Buffer.getUint32(0, buf) == 1ul
+```
+
 ### Buffer.**addUint32**
 
 <details disabled>
@@ -1015,6 +1315,14 @@ Parameters:
 |`value`|`Uint32`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint32(1ul, buf)
+assert Buffer.getUint32(0, buf) == 1ul
+```
+
 ### Buffer.**getFloat32**
 
 <details disabled>
@@ -1049,6 +1357,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addFloat32(1.0f, buf)
+assert Buffer.getFloat32(0, buf) == 1.0f
+```
+
 ### Buffer.**setFloat32**
 
 <details disabled>
@@ -1078,6 +1394,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 4` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setFloat32(0, 1.0f, buf)
+assert Buffer.getFloat32(0, buf) == 1.0f
+```
+
 ### Buffer.**addFloat32**
 
 <details disabled>
@@ -1098,6 +1423,14 @@ Parameters:
 |`value`|`Float32`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addFloat32(1.0f, buf)
+assert Buffer.getFloat32(0, buf) == 1.0f
+```
+
 ### Buffer.**getInt64**
 
 <details disabled>
@@ -1132,6 +1465,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addInt64(1L, buf)
+assert Buffer.getInt64(0, buf) == 1L
+```
+
 ### Buffer.**setInt64**
 
 <details disabled>
@@ -1161,6 +1502,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setInt64(0, 1L, buf)
+assert Buffer.getInt64(0, buf) == 1L
+```
+
 ### Buffer.**addInt64**
 
 <details disabled>
@@ -1181,6 +1531,14 @@ Parameters:
 |`value`|`Int64`|The value to set|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addInt64(1L, buf)
+assert Buffer.getInt64(0, buf) == 1L
+```
+
 ### Buffer.**getUint64**
 
 <details disabled>
@@ -1215,6 +1573,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint64(1uL, buf)
+assert Buffer.getUint64(0, buf) == 1uL
+```
+
 ### Buffer.**setUint64**
 
 <details disabled>
@@ -1244,6 +1610,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setUint64(0, 1uL, buf)
+assert Buffer.getUint64(0, buf) == 1uL
+```
+
 ### Buffer.**addUint64**
 
 <details disabled>
@@ -1264,6 +1639,14 @@ Parameters:
 |`value`|`Uint64`|The value to set|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addUint64(1uL, buf)
+assert Buffer.getUint64(0, buf) == 1uL
+```
+
 ### Buffer.**getFloat64**
 
 <details disabled>
@@ -1298,6 +1681,14 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addFloat64(1.0F, buf)
+assert Buffer.getFloat64(0, buf) == 1.0F
+```
+
 ### Buffer.**setFloat64**
 
 <details disabled>
@@ -1327,6 +1718,15 @@ Throws:
 * When `index` is greater than or equal to the buffer size
 * When `index + 8` is greater than the buffer size
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addString("Hello World", buf)
+Buffer.setFloat64(0, 1.0F, buf)
+assert Buffer.getFloat64(0, buf) == 1.0F
+```
+
 ### Buffer.**addFloat64**
 
 <details disabled>
@@ -1347,3 +1747,11 @@ Parameters:
 |`value`|`Float64`|The value to append|
 |`buffer`|`Buffer`|The buffer to mutate|
 
+Examples:
+
+```grain
+let buf = Buffer.make(32)
+Buffer.addFloat64(1.0F, buf)
+assert Buffer.getFloat64(0, buf) == 1.0F
+```
+