1 files changed, 47 insertions, 48 deletions
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