Doc: Fix documentation warnings for QJni* classes

Pick-to: 6.1
Change-Id: Iab836fbdf649f1b3b60e88d32266361299ac4bb2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

src/corelib/doc/include/jni.h

@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtCore module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#pragma once
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API. It exists purely as an
+// implementation detail. This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
+// Dummy declarations for generating docs on non-Android platforms
+#if !defined(Q_OS_ANDROID) && defined(Q_QDOC)
+typedef struct {} JNIEnv;
+typedef struct {} JNINativeMethod;
+struct _jclass;
+typedef _jclass* jclass;
+struct _jobject;
+typedef _jobject* jobject;
+typedef void* JavaVM;
+#endif

src/corelib/doc/qtcore.qdocconf

@@ -5,6 +5,8 @@ project                 = QtCore
 description             = Qt Core Reference Documentation
 version                 = $QT_VERSION
 
+includepaths           += ./include
+
 examplesinstallpath     = corelib
 
 qhp.projects            = QtCore

src/corelib/kernel/qjnienvironment.cpp

@@ -158,7 +158,7 @@ JNIEnv &QJniEnvironment::operator*() const
 }
 
 /*!
-    \fn JNIEnv *QJniEnvironment::jniEnv()
+    \fn JNIEnv *QJniEnvironment::jniEnv() const
 
     Returns the JNI Environment's \c JNIEnv pointer.
 */

src/corelib/kernel/qjnienvironment.h

@@ -42,7 +42,7 @@
 
 #include <QtCore/QScopedPointer>
 
-#if defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED)
+#if defined(Q_QDOC) || (defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED))
 #include <jni.h>
 
 QT_BEGIN_NAMESPACE

src/corelib/kernel/qjniobject.cpp

@@ -638,8 +638,6 @@ QJniObject::QJniObject(const char *className, const char *signature, const QVaLi
 }
 
 /*!
-    \fn QJniObject::QJniObject(jclass clazz, const char *signature, ...)
-
     Constructs a new JNI object from \a clazz by calling the constructor with
     \a signature specifying the types of any subsequent arguments.
 
@@ -672,8 +670,6 @@ QJniObject::QJniObject(jclass clazz, const char *signature, ...)
 }
 
 /*!
-    \fn QJniObject::QJniObject(jclass clazz)
-
     Constructs a new JNI object by calling the default constructor of \a clazz.
 
     \note The QJniObject will create a new reference to the class \a clazz
@@ -719,8 +715,6 @@ QJniObject::QJniObject(jclass clazz, const char *signature, const QVaListPrivate
 }
 
 /*!
-    \fn QJniObject::QJniObject(jobject object)
-
     Constructs a new JNI object around the Java object \a object.
 
     \note The QJniObject will hold a reference to the Java object \a object
@@ -732,15 +726,15 @@ QJniObject::QJniObject(jclass clazz, const char *signature, const QVaListPrivate
 
     \sa fromLocalRef()
 */
-QJniObject::QJniObject(jobject obj)
+QJniObject::QJniObject(jobject object)
     : d(new QJniObjectPrivate())
 {
-    if (!obj)
+    if (!object)
         return;
 
     QJniEnvironment env;
-    d->m_jobject = env->NewGlobalRef(obj);
-    jclass cls = env->GetObjectClass(obj);
+    d->m_jobject = env->NewGlobalRef(object);
+    jclass cls = env->GetObjectClass(object);
     d->m_jclass = static_cast<jclass>(env->NewGlobalRef(cls));
     env->DeleteLocalRef(cls);
 }
@@ -750,19 +744,19 @@ QJniObject::QJniObject(jobject obj)
     exception clearing and delete the local reference before returning.
     The JNI object can be null if there was an exception.
 */
-QJniObject QJniObject::getCleanJniObject(jobject obj)
+QJniObject QJniObject::getCleanJniObject(jobject object)
 {
-    if (!obj)
+    if (!object)
         return QJniObject();
 
     QJniEnvironment env;
     if (env.checkAndClearExceptions()) {
-        env->DeleteLocalRef(obj);
+        env->DeleteLocalRef(object);
         return QJniObject();
     }
 
-    QJniObject res(obj);
-    env->DeleteLocalRef(obj);
+    QJniObject res(object);
+    env->DeleteLocalRef(object);
     return res;
 }
 
@@ -775,12 +769,14 @@ QJniObject::~QJniObject()
 {}
 
 /*!
-    \fn jobject QJniObject::object() const
+    \fn template <typename T> T QJniObject::object() const
 
-    Returns the object held by the QJniObject as jobject.
+    Returns the object held by the QJniObject either as jobject or as type T.
+    T can be one of \l {Object Types}{JNI Object Types}.
 
     \code
-    jobject object = jniObject.object();
+    QJniObject string = QJniObject::fromString("Hello, JNI");
+    jstring jstring = string.object<jstring>();
     \endcode
 
     \note The returned object is still kept live by this QJniObject. To keep the
@@ -1090,26 +1086,6 @@ QJniObject QJniObject::callStaticObjectMethod(jclass clazz, jmethodID methodId,
 
 */
 
-/*!
-    \fn template <typename T> T QJniObject::object() const
-
-    Returns the object held by the QJniObject as type T.
-    T can be one of \l {Object Types}{JNI Object Types}.
-
-    \code
-    QJniObject string = QJniObject::fromString("Hello, JNI");
-    jstring jstring = string.object<jstring>();
-    \endcode
-
-    \note The returned object is still kept live by this QJniObject. To keep the
-    object live beyond the lifetime of this QJniObject, for example to record it
-    for later use, the easiest approach is to store it in another QJniObject with
-    a suitable lifetime. Alternatively, you can make a new global reference to the
-    object and store it, taking care to free it when you are done with it.
-
-    \snippet jni/src_qjniobject.cpp QJniObject scope
-*/
-
 /*!
     \fn template <typename T> QJniObject &QJniObject::operator=(T object)
 
@@ -1169,7 +1145,7 @@ QJniObject QJniObject::callStaticObjectMethod(jclass clazz, jmethodID methodId,
 /*!
     \fn QJniObject QJniObject::getStaticObjectField(const char *className, const char *fieldName, const char *signature)
 
-    Retrieves a JNI object from the field \a filedName with \a signature from
+    Retrieves a JNI object from the field \a fieldName with \a signature from
     class \a className.
 
     \note This function can be used without a template type.

src/corelib/kernel/qjniobject.h

@@ -42,7 +42,7 @@
 
 #include <QtCore/qsharedpointer.h>
 
-#if defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED)
+#if defined(Q_QDOC) || (defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED))
 #include <jni.h>
 #include <QtCore/qjnienvironment.h>