6 files changed, 51 insertions, 111 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index becffaa9..14ba6d69 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -31,8 +31,8 @@ It provides a C language API.
 The following common functions exist in _libnng_.
 
 |===
-|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory
-|xref:nng_free.3.adoc[nng_free()]|free memory
+//|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory
+//|xref:nng_free.3.adoc[nng_free()]|free memory
 |xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string
 |xref:nng_strerror.3.adoc[nng_strerror()]|return an error description
 |xref:nng_strfree.3.adoc[nng_strfree()]|free string
diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc
deleted file mode 100644
index 93c03111..00000000
--- a/docs/man/nng_alloc.3.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-= nng_alloc(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_alloc - allocate memory
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void *nng_alloc(size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_alloc()` function allocates a contiguous memory region of
-at least _size_ bytes.
-The memory will be 64-bit aligned.
-
-The returned memory can be used to hold message buffers, in which
-case it can be directly passed to xref:nng_send.3.adoc[`nng_send()`] using
-the flag `NNG_FLAG_ALLOC`.  Alternatively, it can be freed when no
-longer needed using xref:nng_free.3.adoc[`nng_free()`].
-
-IMPORTANT: Do not use the system `free()` function to release this memory.
-On some platforms this may work, but it is not guaranteed and may lead
-to a crash or other undesirable and unpredictable behavior.
-
-== RETURN VALUES
-
-This function returns a pointer to the allocated memory on success,
-and `NULL` otherwise.
-
-== ERRORS
-
-No errors are returned, but a `NULL` return value should be
-treated the same as `NNG_ENOMEM`.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng_send.3.adoc[nng_send(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_free.3.adoc b/docs/man/nng_free.3.adoc
deleted file mode 100644
index b4fdc249..00000000
--- a/docs/man/nng_free.3.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-= nng_free(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_free - free memory
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_free(void *ptr, size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_free()` function deallocates a memory region of size _size_,
-that was previously allocated by xref:nng_alloc.3.adoc[`nng_alloc()`] or
-xref:nng_recv.3.adoc[`nng_recv()`] with the `NNG_FLAG_ALLOC` flag.
-
-IMPORTANT: It is very important that _size_ match the allocation size
-used to allocate the memory.
-
-IMPORTANT: Do not attempt to use this function to deallocate memory
-obtained by a call to the system `malloc()` or `calloc()` functions,
-or the {cpp} `new` operator.
-Doing so may result in unpredictable
-behavior, including corruption of application memory.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_recv.3.adoc[nng_recv(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 193b316f..59010794 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -8,6 +8,7 @@
 
   - [Utility Functions](./api/util/index.md)
 
+    - [nng_alloc](./api/util/nng_alloc.md)
     - [nng_clock](./api/util/nng_clock.md)
     - [nng_id_map](./api/util/nng_id_map.md)
     - [nng_msleep](./api/util/nng_msleep.md)
diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md
index 0a96da44..24c88d9c 100644
--- a/docs/ref/api/util/index.md
+++ b/docs/ref/api/util/index.md
@@ -5,6 +5,7 @@ with application portability. These are not fundamental to NNG
 or Scalability Protocols, but we find them useful for a variety
 of other uses.
 
+- [nng_alloc](nng_alloc.md)
 - [nng_clock](nng_clock.md)
 - [nng_id_map](nng_id_map.md)
 - [nng_msleep](nng_msleep.md)
diff --git a/docs/ref/api/util/nng_alloc.md b/docs/ref/api/util/nng_alloc.md
new file mode 100644
index 00000000..39b7bc2c
--- /dev/null
+++ b/docs/ref/api/util/nng_alloc.md
@@ -0,0 +1,47 @@
+# 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]