From d831035435dac02006751d7bdd74160451f50adf Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Mon, 3 May 2021 13:18:03 +0200 Subject: [PATCH] Doc: Fix documentation warnings for QJni* classes Pick-to: 6.1 Change-Id: Iab836fbdf649f1b3b60e88d32266361299ac4bb2 Reviewed-by: Paul Wicking --- src/corelib/doc/include/jni.h | 62 ++++++++++++++++++++++++++ src/corelib/doc/qtcore.qdocconf | 2 + src/corelib/kernel/qjnienvironment.cpp | 2 +- src/corelib/kernel/qjnienvironment.h | 2 +- src/corelib/kernel/qjniobject.cpp | 54 +++++++--------------- src/corelib/kernel/qjniobject.h | 2 +- 6 files changed, 82 insertions(+), 42 deletions(-) create mode 100644 src/corelib/doc/include/jni.h diff --git a/src/corelib/doc/include/jni.h b/src/corelib/doc/include/jni.h new file mode 100644 index 0000000000..09186969dd --- /dev/null +++ b/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 diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf index 895dcb7b0a..3699bc84c3 100644 --- a/src/corelib/doc/qtcore.qdocconf +++ b/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 diff --git a/src/corelib/kernel/qjnienvironment.cpp b/src/corelib/kernel/qjnienvironment.cpp index 0e6cafcd91..5aee05bce6 100644 --- a/src/corelib/kernel/qjnienvironment.cpp +++ b/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. */ diff --git a/src/corelib/kernel/qjnienvironment.h b/src/corelib/kernel/qjnienvironment.h index 2053e0a50f..66835f7c68 100644 --- a/src/corelib/kernel/qjnienvironment.h +++ b/src/corelib/kernel/qjnienvironment.h @@ -42,7 +42,7 @@ #include -#if defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED) +#if defined(Q_QDOC) || (defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED)) #include QT_BEGIN_NAMESPACE diff --git a/src/corelib/kernel/qjniobject.cpp b/src/corelib/kernel/qjniobject.cpp index 319a7ba0d1..c443746ff4 100644 --- a/src/corelib/kernel/qjniobject.cpp +++ b/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(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 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(); \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 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(); - \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 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. diff --git a/src/corelib/kernel/qjniobject.h b/src/corelib/kernel/qjniobject.h index 011a1c0185..e7bf4f3007 100644 --- a/src/corelib/kernel/qjniobject.h +++ b/src/corelib/kernel/qjniobject.h @@ -42,7 +42,7 @@ #include -#if defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED) +#if defined(Q_QDOC) || (defined(Q_OS_ANDROID) && !defined(Q_OS_ANDROID_EMBEDDED)) #include #include