log: install_message_handler takes Option<fn> + docs

This is breaking change for old code.

Author: ratijas

qmetaobject/src/log.rs

@@ -123,10 +123,22 @@ impl From<Level> for QtMsgType {
     }
 }
 
-/// Wrap qt's qInstallMessageHandler.
-/// Useful in order to forward the log to a rust logging framework
-pub fn install_message_handler(logger: extern "C" fn(QtMsgType, &QMessageLogContext, &QString)) {
-    cpp!(unsafe [logger as "QtMessageHandler"] { qInstallMessageHandler(logger); })
+/// Wrapper for [`QtMessageHandler`][] typedef.
+///
+/// [`QtMessageHandler`]: https://doc.qt.io/qt-5/qtglobal.html#QtMessageHandler-typedef
+pub type QtMessageHandler = Option<extern "C" fn(QtMsgType, &QMessageLogContext, &QString)>;
+
+/// Wrapper for [`qInstallMessageHandler`] function.
+///
+/// # Wrapper-specific behavior
+///
+/// To restore the message handler, call `install_message_handler(None)`.
+///
+/// [`qInstallMessageHandler`]: https://doc.qt.io/qt-5/qtglobal.html#qInstallMessageHandler
+pub fn install_message_handler(logger: QtMessageHandler) -> QtMessageHandler {
+    cpp!(unsafe [logger as "QtMessageHandler"] -> QtMessageHandler as "QtMessageHandler" {
+        return qInstallMessageHandler(logger);
+    })
 }
 
 // Logging middleware, pass-though, or just proxy function.
@@ -188,7 +200,7 @@ pub fn init_qt_to_rust() {
     // The reason it is named so complex instead of simple `init` is that
     // such descriptive name is future-proof. Consider if someone someday
     // would want to implement the opposite forwarding logger?
-    install_message_handler(log_capture);
+    install_message_handler(Some(log_capture));
 }
 
 #[cfg(test)]

qmetaobject/tests/common/mod.rs

@@ -52,7 +52,7 @@ pub fn do_test<T: QObject + Sized>(obj: T, qml: &str) -> bool {
     let _lock = lock_for_test();
     QML_LOGS.lock().unwrap_or_else(|e| e.into_inner()).clear();
 
-    install_message_handler(log_capture);
+    install_message_handler(Some(log_capture));
 
     let qml_text = "import QtQuick 2.0\n".to_owned() + qml;
 
@@ -69,7 +69,7 @@ pub fn do_test_error_with_url<T: QObject + Sized>(obj: T, qml: &str, url: &str)
     let _lock = lock_for_test();
     QML_LOGS.lock().unwrap_or_else(|e| e.into_inner()).clear();
 
-    install_message_handler(log_capture);
+    install_message_handler(Some(log_capture));
 
     let qml_text = "import QtQuick 2.0\n".to_owned() + qml;
 
@@ -87,7 +87,7 @@ pub fn do_test_variant(obj: QVariant, qml: &str) -> bool {
     let _lock = lock_for_test();
     QML_LOGS.lock().unwrap_or_else(|e| e.into_inner()).clear();
 
-    install_message_handler(log_capture);
+    install_message_handler(Some(log_capture));
 
     let qml_text = "import QtQuick 2.0\n".to_owned() + qml;
 
@@ -101,7 +101,7 @@ pub fn test_loading_logs(qml: &str, log: &str) -> bool {
     let _lock = TEST_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
     QML_LOGS.lock().unwrap_or_else(|e| e.into_inner()).clear();
 
-    install_message_handler(log_capture);
+    install_message_handler(Some(log_capture));
 
     let qml_text = "import QtQuick 2.0\n".to_owned() + qml;