api: extend usage of nng_err

This replaces the int, and we will expand this further, as this
makes it clear that the int is actually an error code and helps in
debuggers that can provide symbolic values.

3 files changed, 20 insertions, 21 deletions

diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md
index 1e6f76fa..dcf9aa85 100644
--- a/docs/ref/api/aio.md
+++ b/docs/ref/api/aio.md
@@ -81,7 +81,7 @@ is safe to call from _aio_'s own callback.
 ## Cancellation
 
 ```c
-void nng_aio_abort(nng_aio *aio, int err);
+void nng_aio_abort(nng_aio *aio, nng_err err);
 void nng_aio_cancel(nng_aio *aio);
 void nng_aio_stop(nng_aio *aio);
 ```
@@ -169,7 +169,7 @@ This is the same test used internally by [`nng_aio_wait`].
 ## Result of Operation
 
 ```c
-int nng_aio_result(nng_aio *aio);
+nng_err nng_aio_result(nng_aio *aio);
 size_t nng_aio_count(nng_aio *aio);
 ```
 
diff --git a/docs/ref/api/errors.md b/docs/ref/api/errors.md
index 2a4ccc93..c7a50780 100644
--- a/docs/ref/api/errors.md
+++ b/docs/ref/api/errors.md
@@ -1,5 +1,9 @@
 # Errors
 
+```c
+typedef enum ... nng_err;
+```
+
 Many _NNG_ functions can fail for a variety of reasons.
 These functions tend to return either zero on success,
 or a non-zero error code to indicate failure.
@@ -7,7 +11,11 @@ or a non-zero error code to indicate failure.
 which behave the same way, but _NNG_ does not use a separate
 _errno_ variable.}}
 
-All these error codes are `int`.
+All these error codes are `nng_err`.
+
+> [!NOTE]
+> Many APIs are still using `int`, but the `nng_err` enumeration can be used
+> instead, and will help with debugging.
 
 Not every possible error code is defined here, as sometimes
 an underlying system or library error code is "wrapped".
@@ -15,7 +23,7 @@ an underlying system or library error code is "wrapped".
 ## Human Readable Error Message
 
 ```c
-const char *nng_strerror(int err);
+const char *nng_strerror(nng_err err);
 ```
 
 The {{i:`nng_strerror`}} returns the human-readable description of the
diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md
index 48b09300..da3d22d4 100644
--- a/docs/ref/api/http.md
+++ b/docs/ref/api/http.md
@@ -56,7 +56,7 @@ set when issuing the transaction.
 ### HTTP URI
 
 ```c
-int nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
+nng_err nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
 const char *nng_http_get_uri(nng_http *conn);
 ```
 
@@ -76,7 +76,7 @@ will have any query concentated, for example "/api/get_user.cgi?name=garrett".
 ### HTTP Version
 
 ```c
-int nng_http_set_version(nng_http *conn, const char *version);
+nng_err nng_http_set_version(nng_http *conn, const char *version);
 const char *nng_http_get_version(nng_http *conn);
 ```
 
@@ -210,8 +210,8 @@ The scan can be rest by setting _next_ to `NULL`.
 ### Modifying Headers
 
 ```c
-int nng_http_add_header(nng_http *conn, const char *key, const char *val);
-int nng_http_set_header(nng_http *conn, const char *key, const char *val);
+nng_err nng_http_add_header(nng_http *conn, const char *key, const char *val);
+nng_err nng_http_set_header(nng_http *conn, const char *key, const char *val);
 void nng_http_del_header(nng_http *conn, const char *key);
 ```
 
@@ -323,7 +323,7 @@ They can be used to transfer request or response body data as well.
 ### Hijacking Connections
 
 ```c
-void nng_http_hijack(nng_http_conn *conn);
+nng_err nng_http_hijack(nng_http *conn);
 ```
 
 TODO: This API will change to convert the conn into a stream object.
@@ -387,8 +387,8 @@ of its resources.
 ### Client TLS
 
 ```c
-int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
-int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
+nng_err nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
+nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
 ```
 
 The {{i:`nng_http_client_get_tls`}} and {{i:`nng_http_client_set_tls`}} functions are used to
@@ -456,15 +456,6 @@ if ((rv = nng_aio_result(aio)) != 0) {
 
 ### Preparing a Transaction
 
-```c
-int nng_http_set_version(nng_http *conn, const char *version);
-int nng_http_set_uri(nng_http *conn, const char *uri);
-```
-
-The {{i:`nng_http_set_uri`}} function provides a URI for the transaction. This will be used to
-set the URI for the request. The URI typically appears like a path, starting with "/", although
-it may also contain a query string.
-
 ### Request Body
 
 ### Sending the Request
@@ -510,7 +501,7 @@ It does _not_ transfer any response body. To do that, use [`nng_http_read_all`]
 ### Submitting the Transaction
 
 ```c
-int nng_http_transact(nng_http *conn, nng_aio *aio);
+void nng_http_transact(nng_http *conn, nng_aio *aio);
 ```
 
 The HTTP request is issued, and the response processed, asynchronously by the {{i:`nng_http_transact`}} function.