feat: ConnectionHandle::release to ignore warning

As described in #43, you now get a warning if you don't use the
ConnectionHandle that is returned by connecting to a signal.
But as @lemirep noted, this can be annoying without a proper way to
silence the warning.
This commit adds a `release` function that can simply be used to ignore
the nodiscard warning intentionally.

Fix #43

src/kdbindings/connection_handle.h

@@ -180,6 +180,23 @@ class ConnectionHandle
         return false;
     }
 
+    /**
+     * This function exists to intentionally silence the [[nodiscard]] warning generated when connecting.
+     *
+     * In cases where you know for certain that the lifetime of the signal does not extend beyond the lifetime of the slot, you may not need the ConnectionHandle, so you can use release to discard it.
+     *
+     * Example:
+     * ```cpp
+     * bool called = false;
+     * {
+     *     Signal<int> mySignal;
+     *     // The signal will not outlive the reference to the `called` bool, so it's fine to ignore the ConnectionHandle.
+     *     mySignal.connect([&called](){ called = true; }).release();
+     * }
+     * ```
+     */
+    void release() const { }
+
 private:
     template<typename...>
     friend class Signal;

src/kdbindings/signal.h

@@ -355,7 +355,7 @@ class Signal
      * All connected functions should handle their own exceptions.
      * For backwards-compatibility, the slot function is not required to be noexcept.
      */
-    ConnectionHandle connectReflective(std::function<void(ConnectionHandle &, Args...)> const &slot)
+    KDBINDINGS_WARN_UNUSED ConnectionHandle connectReflective(std::function<void(ConnectionHandle &, Args...)> const &slot)
     {
         ensureImpl();
 

tests/signal/tst_signal.cpp

@@ -798,6 +798,16 @@ TEST_CASE("ConnectionHandle")
         REQUIRE_FALSE(handle.belongsTo(signal));
         REQUIRE(handle.belongsTo(otherSignal));
     }
+
+    SUBCASE("A ConnectinHandle can be released to ignore the nodiscard warning")
+    {
+        bool called = false;
+        {
+            Signal<int> mySignal;
+            // As long as this compiles without error, the test can pass, no need to REQUIRE anything
+            mySignal.connect([&called]() { called = true; }).release();
+        }
+    }
 }
 
 TEST_CASE("ScopedConnection")