Documentation improvements to JNI API

Amends 4e60681c879a54cf5b34862a30e27c492ed36363.

Fixes: QTBUG-89632
Pick-to: 6.1
Change-Id: I7856e9b63eea5ba68a5472575016540ae656ec5f
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

2 files changed, 33 insertions, 15 deletions

diff --git a/src/corelib/doc/snippets/jni/src_qjniobject.cpp b/src/corelib/doc/snippets/jni/src_qjniobject.cpp
index f3433134db..b729987d4f 100644
--- a/src/corelib/doc/snippets/jni/src_qjniobject.cpp
+++ b/src/corelib/doc/snippets/jni/src_qjniobject.cpp
@@ -79,7 +79,7 @@ void functionScope()
 }
 //! [QJniObject scope]
 
-//! [Registering native methods]
+//! [C++ native methods]
 static void fromJavaOne(JNIEnv *env, jobject thiz, jint x)
 {
     Q_UNUSED(env);
@@ -94,26 +94,19 @@ static void fromJavaTwo(JNIEnv *env, jobject thiz, jint x)
     qDebug() << x << ">= 100";
 }
 
-void registerNativeMethods() {
+void foo()
+{
+    // register the native methods first, ideally it better be done with the app start
     JNINativeMethod methods[] {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                                {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
-
-    QJniObject javaClass("my/java/project/FooJavaClass");
     QJniEnvironment env;
-    jclass objectClass = env->GetObjectClass(javaClass.object<jobject>());
-    env->RegisterNatives(objectClass,
-                         methods,
-                         sizeof(methods) / sizeof(methods[0]));
-    env->DeleteLocalRef(objectClass);
-}
+    env.registerNativeMethods("my/java/project/FooJavaClass", methods, 2);
 
-void foo()
-{
+    // Call the java method which will calls back to the C++ functions
     QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 10);  // Output: 10 < 100
     QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 100); // Output: 100 >= 100
 }
-
-//! [Registering native methods]
+//! [C++ native methods]
 
 //! [Java native methods]
 class FooJavaClass
diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc
index c3dc67a705..583e668be4 100644
--- a/src/corelib/doc/src/external-resources.qdoc
+++ b/src/corelib/doc/src/external-resources.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -65,3 +65,28 @@
     \externalpage https://marcmutz.wordpress.com/effective-qt/containers/
     \title Understand the Qt Containers
 */
+
+/*!
+    \externalpage https://developer.android.com/training/articles/perf-jni#javavm-and-jnienv
+    \title JNI tips: JavaVM and JNIEnv
+*/
+
+/*!
+    \externalpage https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html
+    \title Java Native Interface Specification
+*/
+
+/*!
+    \externalpage https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html
+    \title Oracle: JNI Functions
+*/
+
+/*!
+    \externalpage https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/design.html#global_and_local_references
+    \title JNI Design Overview: Global and Local References
+*/
+
+/*!
+    \externalpage https://developer.android.com/training/articles/perf-jni#local-and-global-references
+    \title JNI tips: Local and global references
+*/