From d3eba1871847528897f2d544817b4c90bd9678c2 Mon Sep 17 00:00:00 2001
From: CodeYan01 <65320293+CodeYan01@users.noreply.github.com>
Date: Thu, 24 Nov 2022 03:16:16 +0800
Subject: [PATCH] docs: Clarify signal_handler_connect()

Notes that it does nothing if the combination of `signal`,
`callback`, and `data` is already connected to the handler.
Adds missing param `signal` description.
Typo fix
---
 docs/sphinx/reference-libobs-callback.rst | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/docs/sphinx/reference-libobs-callback.rst b/docs/sphinx/reference-libobs-callback.rst
index ff741a832..494efa23b 100644
--- a/docs/sphinx/reference-libobs-callback.rst
+++ b/docs/sphinx/reference-libobs-callback.rst
@@ -192,11 +192,14 @@ Signals are used for all event-based callbacks.
 
 .. function:: void signal_handler_connect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)
 
-   Connect a callback to a signal on a signal handler.
+   Connects a callback to a signal on a signal handler. Does nothing
+   if the combination of ``signal``, ``callback``, and ``data``
+   is already connected to the handler.
 
    :param handler:  Signal handler object
+   :param signal:   Name of signal to handle
    :param callback: Signal callback
-   :param data:     Private data passed the callback
+   :param data:     Private data passed to the callback
 
    For scripting, use :py:func:`signal_handler_connect`.
 
@@ -204,23 +207,29 @@ Signals are used for all event-based callbacks.
 
 .. function:: void signal_handler_connect_ref(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)
 
-   Connect a callback to a signal on a signal handler, and increments
+   Connects a callback to a signal on a signal handler, and increments
    the handler's internal reference counter, preventing it from being
-   destroyed until the signal has been disconnected.
+   destroyed until the signal has been disconnected. Even if the combination of
+   ``signal``, ``callback``, and ``data`` is already connected to the handler,
+   the reference counter is still incremented.
 
    :param handler:  Signal handler object
+   :param signal:   Name of signal to handle
    :param callback: Signal callback
-   :param data:     Private data passed the callback
+   :param data:     Private data passed to the callback
 
 ---------------------
 
 .. function:: void signal_handler_disconnect(signal_handler_t *handler, const char *signal, signal_callback_t callback, void *data)
 
-   Disconnects a callback from a signal on a signal handler.
+   Disconnects a callback from a signal on a signal handler. Does nothing
+   if the combination of ``signal``, ``callback``, and ``data``
+   is not yet connected to the handler.
 
    :param handler:  Signal handler object
+   :param signal:   Name of signal that was handled
    :param callback: Signal callback
-   :param data:     Private data passed the callback
+   :param data:     Private data passed to the callback
 
    For scripting, use :py:func:`signal_handler_disconnect`.