docs: add memory chapter

5 files changed, 78 insertions, 104 deletions

diff --git a/docs/book.toml b/docs/book.toml
index 5b7a2610..a9abb5f1 100644
--- a/docs/book.toml
+++ b/docs/book.toml
@@ -18,7 +18,7 @@ additional-js = ["theme/pagetoc.js"]
 
 [preprocessor.footnote]
 
-# [preprocessor.inline-highlighting]
+[preprocessor.inline-highlighting]
 # default-language = "c"
 
 [preprocessor.pagetoc]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 9cb0de6a..1b7d873e 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -8,6 +8,8 @@
 
   - [Messages](./api/msg.md)
 
+  - [Memory](./api/memory.md)
+
   - [Time](./api/time.md)
 
   - [Asynchronous Operations](./api/aio/index.md)
@@ -25,12 +27,10 @@
 
   - [Utility Functions](./api/util/index.md)
 
-    - [nng_alloc](./api/util/nng_alloc.md)
     - [nng_id_map](./api/util/nng_id_map.md)
     - [nng_opts_parse](./api/util/nng_opts_parse.md)
     - [nng_random](./api/util/nng_random.md)
     - [nng_socket_pair](./api/util/nng_socket_pair.md)
-    - [nng_strdup](./api/util/nng_strdup.md)
     - [nng_strerror](./api/util/nng_strerror.md)
     - [nng_url](./api/util/nng_url.md)
     - [nng_version](./api/util/nng_version.md)
diff --git a/docs/ref/api/memory.md b/docs/ref/api/memory.md
new file mode 100644
index 00000000..02748123
--- /dev/null
+++ b/docs/ref/api/memory.md
@@ -0,0 +1,75 @@
+# Memory
+
+Managing {{i:memory}} and {{i:allocations}} is something that every C program has to deal with.
+In the case of _NNG_, it can be more complicated because the underlying platform
+code can provide different allocators that might not be compatible with the use
+system allocator used by `malloc` and `free`.
+
+## Allocate Memory
+
+```c
+void *nng_alloc(size_t size);
+```
+
+The {{i:`nng_alloc`}} function allocates a contiguous memory region of
+at least _size_ bytes, and returns a pointer to it.
+The memory will be 64-bit aligned.
+Note that the memory may have random data in it, just like with `malloc`.
+
+If memory cannot be allocated for any reason, then `NULL` will be returned.
+Applications that experience this should treat this like `NNG_ENOMEM`.
+
+Memory returned by `nng_alloc` can be used to hold message buffers, in which
+case it can be directly passed to [`nng_send`][nng_send] using the flag `NNG_FLAG_ALLOC`.
+Alternatively, it can be freed when no longer needed using [`nng_free`][nng_free].
+
+> [!IMPORTANT]
+> Do not use the system `free` function (or the C++ `delete` operator) to release this memory.
+> On some configurations this may work, but on others it will lead to a crash or
+> other unpredictable behavior.
+
+## Deallocate Memory
+
+```c
+void nng_free(void *ptr, size_t size);
+```
+
+The {{i:`nng_free`}} function deallocates memory previously allocated by [`nng_alloc`][nng_alloc].
+
+The _size_ argument must exactly match the _size_ argument that was supplied to
+`nng_alloc` when the memory was allocated.
+
+## Duplicate String
+
+```c
+char *nng_strdup(const char *src);
+```
+
+The {{i:`nng_strdup`}} duplicates the string _src_ and returns it.
+
+This is logically equivalent to using [`nng_alloc`][nng_alloc]
+to allocate a region of memory of `[c] strlen(s) + 1` bytes, and then
+using `strcpy` to copy the string into the destination before
+returning it.
+
+The returned string should be deallocated with
+[`nng_strfree`][nng_strfree], or may be deallocated using the
+[`nng_free`][nng_free] using the length of the returned string plus
+one (for the `NUL` terminating byte).
+
+## Free String
+
+```c
+void nng_strfree(char *str);
+```
+
+The {{i:`nng_strfree`}} function is a convenience function that
+can be used to deallocate strings allocated with [`nng_strdup`][nng_strdup].
+
+It is effectively the same as `[c] nng_free(strlen(str) + 1)`.
+
+[nng_alloc]: #allocate-memory
+[nng_free]: #deallocate-memory
+[nng_strdup]: #duplicate-string
+[nng_strfree]: #free-string
+[nng_send]: TODO.md
diff --git a/docs/ref/api/util/nng_alloc.md b/docs/ref/api/util/nng_alloc.md
deleted file mode 100644
index 39b7bc2c..00000000
--- a/docs/ref/api/util/nng_alloc.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# nng_alloc
-
-## NAME
-
-nng_alloc --- allocate memory
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-void *nng_alloc(size_t size);
-void nng_free(void *ptr, size_t size);
-```
-
-## DESCRIPTION
-
-The {{i:`nng_alloc`}} function allocates a contiguous memory region of
-at least _size_ bytes.
-The memory will be 64-bit aligned.
-
-The {{i:`nng_free`}} function deallocates {{i:memory}} previously allocated by `nng_alloc`.
-
-Memory returned by `nng_alloc` can be used to hold message buffers, in which
-case it can be directly passed to [`nng_send`][nng_send] using the flag `NNG_FLAG_ALLOC`.
-Alternatively, it can be freed when no longer needed using `nng_free`.
-
-> [!IMPORTANT]
-> Do not use the system `free` function (or the C++ `delete` operator) to release this memory.
-> On some configurations this may work, but on others it will lead to a crash or
-> other unpredictable behavior.
-
-## RETURN VALUES
-
-The `nng_alloc` function returns a pointer to the allocated memory on success,
-and `NULL` otherwise.
-
-## ERRORS
-
-No errors are returned, but if memory cannot be allocated then `NULL` is returned.
-This can reasonably be treated as if an `NNG_ENOMEM` error occurred.
-
-## SEE ALSO
-
-[nng_send][nng_send]
-
-[nng_send]: [TODO.md]
diff --git a/docs/ref/api/util/nng_strdup.md b/docs/ref/api/util/nng_strdup.md
deleted file mode 100644
index 32d3fba2..00000000
--- a/docs/ref/api/util/nng_strdup.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# nng_strdup
-
-## NAME
-
-nng_strdup --- duplicate string
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-char *nng_strdup(const char *src);
-void nng_strfree(char *str);
-```
-
-## DESCRIPTION
-
-The {{i:`nng_strdup`}} duplicates the string _src_ and returns it.
-
-This is logically equivalent to using [`nng_alloc`][nng_alloc]
-to allocate a region of memory of `strlen(s) + 1` bytes, and then
-using `strcpy` to copy the string into the destination before
-returning it.
-
-The returned string should be deallocated with
-{{i:`nng_strfree`}}, or may be deallocated using the
-[`nng_free`][nng_free] using the length of the returned string plus
-one (for the `NUL` terminating byte).
-
-> [!IMPORTANT]
-> Do not use the system `free` or similar functions to deallocate
-> the string, since those may use a different memory arena!
-
-> [!IMPORTANT]
-> If a string created with
-> `nng_strdup` is modified to be shorter, then it is incorrect to free it with `nng_strfree`.
-> (The [`nng_free`][nng_free] function can be used instead in that
-> case, using the length of the original string plus one to account for the `NUL` byte, for the size.)
-
-## RETURN VALUES
-
-The `nng_strdup` function returns the new string on success, and `NULL` on failure.
-
-## ERRORS
-
-No errors are returned from `nng_strdup`, but a `NULL` return value should be
-treated the same as `NNG_ENOMEM`.
-
-## SEE ALSO
-
-[nng_alloc][nng_alloc]
-
-[nng_alloc]: ../util/nng_alloc.md
-[nng_free]: ../util/nng_alloc.md