3 files changed, 117 insertions, 48 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 5813961d..a2572715 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -13,6 +13,11 @@
     - [nng_msg_header](./api/msg/nng_msg_header.md)
     - [nng_msg_pipe](./api/msg/nng_msg_pipe.md)
 
+  - [Asynchronous I/O Operations](./api/aio/index.md)
+
+    - [nng_aio](./api/aio/nng_aio.md)
+    - [aio_cancel](./api/aio/aio_cancel.md)
+
   - [Threading and Synchronization](./api/thr/index.md)
 
     - [nng_cv](./api/thr/nng_cv.md)
diff --git a/docs/ref/api/aio/aio_cancel.md b/docs/ref/api/aio/aio_cancel.md
index 8d4e904b..118c9b5a 100644
--- a/docs/ref/api/aio/aio_cancel.md
+++ b/docs/ref/api/aio/aio_cancel.md
@@ -1,55 +1,54 @@
-= nng_aio_abort(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.
-//
+# aio_cancel
 
-== NAME
+## NAME
 
-nng_aio_abort - abort asynchronous I/O operation
+aio_cancel --- canceling asynchronous I/O
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```c
 #include <nng/nng.h>
 
 void nng_aio_abort(nng_aio *aio, int err);
-----
-
-== DESCRIPTION
-
-The `nng_aio_abort()` function aborts an operation previously started
-with the handle _aio_.
-If the operation is aborted, then the callback
-for the handle will be called, and the function
-xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return the error _err_.
-
-This function does not wait for the operation to be fully aborted, but
-returns immediately.
-
-If no operation is currently in progress (either because it has already
-finished, or no operation has been started yet), then this function
-has no effect.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
-xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
-xref:nng_aio_result.3.adoc[nng_aio_result(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng.7.adoc[nng(7)]
+void nng_aio_cancel(nng_aio *aio);
+void nng_aio_stop(nng_aio *aio);
+```
+
+## DESCRIPTION
+
+These functions are used to stop a previously submitted asynchronous
+I/O operation. The operation may be canceled, or may continue to
+completion. If no operation is in progress (perhaps because it has
+already completed), then these operations have no effect.
+If the operation is successfully canceled or aborted, then the callback
+will still be called.
+
+The {{i:`nng_aio_abort`}} function aborts the operation associated with _aio_
+and returns immediately without waiting. If cancellation was successful,
+then [`nng_aio_result`][nng_aio_result] will return _err_.
+
+The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the error code
+{{i:`NNG_ECANCELED`}}.
+
+The {{i:`nng_aio_stop`}} function aborts the _aio_ operation with `NNG_ECANCELED`,
+and then waits the operation and any associated callback to complete.
+This function also marks _aio_ itself permanently stopped, so that any
+new operations scheduled by I/O providers using [`nng_aio_begin`][nng_aio_begin]
+return false. Thus this function should be used to teardown operations.
+
+> [!TIP]
+> When multiple asynchronous I/O handles are in use and need to be
+> deallocated, it is safest to stop all of them using `nng_aio_stop`,
+> before deallocating any of them with [`nng_aio_free`][nng_aio_free],
+> particularly if the callbacks might attempt to reschedule further operations.
+
+## SEE ALSO
+
+[nng_aio][nng_aio],
+[nng_aio_result][nng_aio_result],
+[nng_aio_free][nng_aio_free]
+
+[nng_aio]: TODO.md
+[nng_aio_begin]: TODO.md
+[nng_aio_result]: TODO.md
+[nng_aio_free]: TODO.md
diff --git a/docs/ref/api/aio/nng_aio.md b/docs/ref/api/aio/nng_aio.md
new file mode 100644
index 00000000..0fdb6ca1
--- /dev/null
+++ b/docs/ref/api/aio/nng_aio.md
@@ -0,0 +1,65 @@
+# nng_aio
+
+## NAME
+
+nng_aio - asynchronous I/O handle
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_aio nng_aio;
+```
+
+## DESCRIPTION
+
+An {{i:`nng_aio`}}{{hi:aio}} is an opaque structure used in conjunction with
+{{i:asynchronous I/O}} operations.
+Every asynchronous operation uses one of these structures, each of which
+can only be used with a single operation at a time.
+
+Asynchronous operations are performed without blocking calling application threads.
+Instead the application registers a callback function to be executed
+when the operation is complete (whether successfully or not).
+This callback will be executed exactly once.
+
+The asynchronous I/O framework also supports cancellation of
+operations that are already in progress
+(see [`nng_aio_cancel`][aio_cancel]), as well setting a maximum
+timeout for them to complete within
+(see [`nng_aio_set_timeout`][nng_aio_set_timeout]).
+
+It is also possible to initiate an asynchronous operation, and wait for it to
+complete using [`nng_aio_wait`][nng_aio_wait].
+
+These structures are created using [`nng_aio_alloc`][nng_aio_alloc],
+and destroyed using [`nng_aio_free`][nng_aio_free].
+
+## SEE ALSO
+
+[nng_aio_cancel][aio_cancel],
+[nng_aio_alloc][nng_aio_alloc],
+[nng_aio_free][nng_aio_free],
+[nng_aio_set_timeout][nng_aio_set_timeout]
+
+<!--
+xref:nng_aio_count.3.adoc[nng_aio_count(3)],
+xref:nng_aio_free.3.adoc[nng_aio_free(3)],
+xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
+xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
+xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
+xref:nng_aio_result.3.adoc[nng_aio_result(3)],
+xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)],
+xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)],
+xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
+xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
+xref:nng_strerror.3.adoc[nng_strerror(3)],
+xref:nng_aio.5.adoc[nng_aio(5)],
+-->
+
+[aio_cancel]: nng_aio_cancel.md
+[nng_aio_alloc]: nng_aio_alloc.md
+[nng_aio_free]: nng_aio_free.md
+[nng_aio_set_timeout]: nng_aio_set_timeout.md
+[nng_aio_wait]: TODO.md