docs: convert http_handler_free doc

2 files changed, 16 insertions, 0 deletions

diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md
index 05821cbc..c02881d5 100644
--- a/docs/ref/api/http.md
+++ b/docs/ref/api/http.md
@@ -644,6 +644,21 @@ sent, if possible, and the connection will be closed.
 
 The _aio_ may be scheduled for deferred completion using the [`nng_aio_start`].
 
+### Freeing Handler
+
+```c
+void nng_http_handler_free(nng_http_handler *h);
+```
+
+The {{i:`nng_http_handler_free`}} function frees an allocated HTTP server handler.
+Normally there is no reason to call this function, because the handler is freed with
+the server it was registered with.
+
+> [!IMPORTANT]
+> It is an error to free a handler that is registered with a server.
+> Any handlers that are registered with servers are automatically freed
+> when the server itself is deallocated.
+
 ### Serving Directories and Files
 
 ```c
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 33c83b2b..e8aa03ea 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -306,6 +306,7 @@
 [`nng_http_write_all`]: ../api/http.md#direct-read-and-write
 [`nng_http_handler`]: ../api/http.md#handlers
 [`nng_http_handler_alloc`]: ../api/http.md#handlers
+[`nng_http_handler_free`]: ../api/http.md#freeing-handler
 [`nng_http_write_response`]: ../api/http.md#sending-the-response-explicitly
 [`nng_http_handler_collect_body`]: ../api/http.md#collecting-request-body
 [`nng_http_handler_set_host`]: ../api/http.md#filtering-byt-host