socket: rename nng_close to nng_socket_close

4 files changed, 29 insertions, 1 deletions

diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md
index 59570240..40190d33 100644
--- a/docs/ref/api/sock.md
+++ b/docs/ref/api/sock.md
@@ -127,6 +127,28 @@ The following functions open a socket in [raw] mode:
 - {{i:`nng_sub0_open_raw`}} - [SUB][sub] version 0, raw mode
 - {{i:`nng_surveyor0_open_raw`}} - [SURVEYOR][surveyor] version 0, raw mode
 
+## Closing a Socket
+
+```c
+int nng_socket_close(nng_socket s);
+```
+
+The {{i:`nng_socket_close`}} function closes a socket, releasing all resources
+associated with it. Any operations that are in progress will be terminated with
+a result of [`NNG_ECLOSED`].
+
+> [!NOTE]
+> Closing a socket also invalidates any [dialers][dialer], [listeners][listener],
+> [pipes][pipe], or [contexts][context] associated with it.
+
+> [!NOTE]
+> This function will wait for any outstanding operations to be aborted, or to complete,
+> before returning. Consequently it is not safe to call this from contexts that cannot
+> block.
+
+> [!NOTE]
+> Closing the socket may be disruptive to transfers that are still in progress.
+
 ## Polling Socket Events
 
 ```c
diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md
index 66add9b2..f7c6b971 100644
--- a/docs/ref/migrate/nanomsg.md
+++ b/docs/ref/migrate/nanomsg.md
@@ -38,7 +38,7 @@ NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent.
 | `nn_strerror`       | [`nng_strerror`]                       |
 | `nn_errno`          | None                                   | Errors are returned directly rather than through `errno`.                                             |
 | `nn_socket`         | Various                                | Use the appropriate protocol constructor, such as `nng_req0_open`.                                    |
-| `nn_close`          | `nng_close`                            |
+| `nn_close`          | `nng_socket_close`                     |
 | `nn_bind`           | `nng_listen`, `nng_listener_create`    | Allocating a listener with `nng_lister_create` and configuring it offers more capabilities.           |
 | `nn_connect`        | `nng_dial`, `nng_dialer_create`        | Allocating a dialer with `nng_dialer_create` and configuring it offers more capabilities.             |
 | `nn_shutdown`       | `nng_lister_close`, `nng_dialer_close` |
diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md
index 62a27432..663bf002 100644
--- a/docs/ref/migrate/nng1.md
+++ b/docs/ref/migrate/nng1.md
@@ -13,6 +13,11 @@ See the [Migrating From libnanomsg](nanomsg.md) chapter for details.
 It is now required for applications to initialize the library explicitly before using it.
 This is done using the [`nng_init`] function.
 
+## Socket Close Function Renamed
+
+The `nng_close` function has been renamed to [`nng_socket_close`] to make it clearer that
+the object being closed is a socket.
+
 ## New AIO Error Code NNG_ESTOPPED
 
 When an operation fails with [`NNG_ESTOPPED`], it means that the associated [`nni_aio`] object has
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 12146752..0dae482c 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -96,6 +96,7 @@
 [`nng_iov`]: /api/aio.md#scatter-gather-vectors
 [`nng_socket_id`]: /api/sock.md#socket-identity
 [`nng_socket_raw`]: /api/sock.md#socket-identity
+[`nng_socket_close`]: /api/sock.md#closing-a-socket
 [`nng_socket_proto_id`]: /api/sock.md#socket-identity
 [`nng_socket_proto_name`]: /api/sock.md#socket-identity
 [`nng_socket_peer_id`]: /api/sock.md#socket-identity