From e372ae06a59d1437e23e3312d1936a0d791d55e5 Mon Sep 17 00:00:00 2001
From: Volker Hilsheimer <volker.hilsheimer@qt.io>
Date: Fri, 31 May 2024 16:28:57 +0200
Subject: [PATCH] JNI: document QJniEnvironment::registerNativeMethods overload

Ideally that doesn't have to be used by clients, as declared types
have a registerNativeMethods static member function that can be
used directly:

QtJniTypes::MyType::registerNativeMethods({...});

But since we don't have documentation for declared types yet (we
could document the QtJniTypes::JObject class perhaps), let's
document this helper for now.

Change-Id: Ic1aca504cc08dfad83b6ba867db24037b1ed7d23
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
(cherry picked from commit 4d6721781806e4ce172f836d4b58df68acc4e4b0)
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
---
 src/corelib/doc/src/jni.qdoc           | 17 ++++++++++++++++-
 src/corelib/kernel/qjnienvironment.cpp | 24 ++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/src/corelib/doc/src/jni.qdoc b/src/corelib/doc/src/jni.qdoc
index f42afbaf946..d05dd44ff60 100644
--- a/src/corelib/doc/src/jni.qdoc
+++ b/src/corelib/doc/src/jni.qdoc
@@ -79,6 +79,17 @@
         writer.callMethod("write", 42);
     }
     \endcode
+
+    In addition to the QJniObject API, those C++ classes also have a static
+    \c{registerNativeMethods} member function that can be used like this:
+
+    \code
+    QtJniTypes::File::registerNativeMethods({
+        Q_JNI_NATIVE_METHOD(freeFunction)
+    });
+    \endcode
+
+    \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_METHOD
 */
 
 /*!
@@ -91,6 +102,7 @@
     QJniEnvironment::registerNativeMethod() with the help of the
     Q_JNI_NATIVE_METHOD macro.
 
+//! [register-free-function]
     \code
     // C++ side
 
@@ -116,6 +128,7 @@
         native public nativeFunction(long id);
     }
     \endcode
+//! [register-free-function]
 
     \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE
 */
@@ -144,12 +157,13 @@
     QJniEnvironment::registerNativeMethod() with the help of the
     Q_JNI_NATIVE_SCOPED_METHOD macro.
 
+//! [register-scoped-function]
     \code
     class NativeHandler
     {
         // ...
     private:
-        static void handleChange((JNIEnv*, jobject, jlong id);
+        static void handleChange(JNIEnv*, jobject, jlong id);
         Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(handleChange)
     };
 
@@ -159,6 +173,7 @@
         Q_JNI_NATIVE_SCOPED_METHOD(handleChange, NativeHandler)
     });
     \endcode
+//! [register-scoped-function]
 
     \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_SCOPED_METHOD
 */
diff --git a/src/corelib/kernel/qjnienvironment.cpp b/src/corelib/kernel/qjnienvironment.cpp
index 1e2826e76be..e890b16f422 100644
--- a/src/corelib/kernel/qjnienvironment.cpp
+++ b/src/corelib/kernel/qjnienvironment.cpp
@@ -320,6 +320,30 @@ JavaVM *QJniEnvironment::javaVM()
 }
 
 /*!
+    \fn template <typename Class> bool QJniEnvironment::registerNativeMethods(std::initializer_list<JNINativeMethods> methods)
+    \overload
+
+    Registers the Java methods in \a methods with the Java class represented by
+    \c Class, and returns whether the registration was successful.
+
+    The \c Class type has to be declared within the QtJniTypes namespace using
+    the Q_DECLARE_JNI_CLASS macro. Functions that are implemented as free C or
+    C++ functions have to be declared using one of the
+    Q_DECLARE_JNI_NATIVE_METHOD macros, and passed into the registration using
+    the Q_JNI_NATIVE_METHOD macro.
+
+    \include jni.qdoc register-free-function
+
+    For functions that are implemented as static class member functions, use
+    the \l{Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE}{macros for scoped
+    functions} instead.
+
+    \include jni.qdoc register-scoped-function
+*/
+
+/*!
+    \overload
+
     Registers the Java methods in the array \a methods of size \a size, each of
     which can call native C++ functions from class \a className. These methods
     must be registered before any attempt to call them.