From 12002c9f7ba6acc2931eba2dc00c41391fd6529f Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 14 Sep 2023 01:08:17 -0700
Subject: nng_aio_stop documentation is badly incorrect

The documentation for this function had not been updated in a long
time, and reflected behavior that is incorrect.
---
 docs/man/nng_aio_stop.3.adoc | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

(limited to 'docs/man/nng_aio_stop.3.adoc')

diff --git a/docs/man/nng_aio_stop.3.adoc b/docs/man/nng_aio_stop.3.adoc
index 65a4790f..94787272 100644
--- a/docs/man/nng_aio_stop.3.adoc
+++ b/docs/man/nng_aio_stop.3.adoc
@@ -1,6 +1,6 @@
 = nng_aio_stop(3)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2023 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
@@ -26,18 +26,15 @@ void nng_aio_stop(nng_aio *aio);
 
 The `nng_aio_stop()` function stops the asynchronous I/O operation
 associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits
-for it to complete or to be completely aborted.
+for it to complete or to be completely aborted, and for the any
+callback associated with the _aio_ to have completed executing.
 
-If an operation is in progress when this function is called, that operation
-is canceled and the callback function is _not_ allowed to run.
+Further calls to
+xref:nng_aio_schedule.3.adoc[`nng_aio_schedule()`] using this _aio_ will fail with
+`NNG_ECLOSED`.
 
-If the callback function is already running when this function is called,
-then it is allowed to complete before returning to the caller.
-
-No new operations will be started on this _aio_.
-
-NOTE: Calling this function means that the operation may be aborted without
-completing its callback function.
+It is safe to call this for an _aio_, even when no operation is currently
+pending for it.
 
 TIP: When multiple asynchronous I/O handles are in use and need to be
 shut down, it is safest to stop all of them, before deallocating any of
@@ -55,9 +52,10 @@ 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_free.3.adoc[nng_aio_free(3)],
+xref:nng_aio_schedule.3.adoc[nng_aio_schedule(3)],
 xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
-xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
 xref:nng_aio.5.adoc[nng_aio(5)],
 xref:nng.7.adoc[nng(7)]
-- 
cgit v1.2.3-70-g09d2

