From b36bf0b3eaa026e22a87865e106f54be6b520811 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 1 Mar 2018 12:40:21 +0100 Subject: Doc: Fix documentation issues when using Clang-enabled QDoc QDoc in Qt 5.11 uses Clang to parse the C++ source for documentation comments. Unlike the old parser, Clang requires a module header to be present as well as correct include paths to generate the docs correctly. However, these are available from the build system only when building for Android, not when generating the documentation on a system with no Android-related assets. To fix this, create a 'dummy' module header specific to doc builds, add required relative include paths in .qdocconf, and fix the documentation \fn commands to work with Clang. Change-Id: Ia3d4e50ff8756cd8c8aae9cd3c3d1492eb7db328 Reviewed-by: Martin Smith --- .../android/qandroidactivityresultreceiver.cpp | 2 +- src/androidextras/android/qandroidservice.cpp | 15 +++++-- .../doc/QtAndroidExtras/QAndroidJniObject | 1 + src/androidextras/doc/QtAndroidExtras/jni.h | 49 ++++++++++++++++++++++ .../doc/QtAndroidExtras/qandroidextrasglobal.h | 2 + .../doc/QtAndroidExtras/qandroidjniobject.h | 1 + src/androidextras/doc/QtAndroidExtrasDoc | 10 +++++ src/androidextras/doc/qtandroidextras.qdocconf | 10 +++++ src/androidextras/jni/qandroidjniobject.cpp | 30 ++++++------- 9 files changed, 101 insertions(+), 19 deletions(-) create mode 100644 src/androidextras/doc/QtAndroidExtras/QAndroidJniObject create mode 100644 src/androidextras/doc/QtAndroidExtras/jni.h create mode 100644 src/androidextras/doc/QtAndroidExtras/qandroidextrasglobal.h create mode 100644 src/androidextras/doc/QtAndroidExtras/qandroidjniobject.h create mode 100644 src/androidextras/doc/QtAndroidExtrasDoc diff --git a/src/androidextras/android/qandroidactivityresultreceiver.cpp b/src/androidextras/android/qandroidactivityresultreceiver.cpp index 3a1acd6..2dfe509 100644 --- a/src/androidextras/android/qandroidactivityresultreceiver.cpp +++ b/src/androidextras/android/qandroidactivityresultreceiver.cpp @@ -110,7 +110,7 @@ QAndroidActivityResultReceiver::~QAndroidActivityResultReceiver() } /*! - \fn void QAndroidActivityResultReceiver::handleActivityResult(int receiverRequestCode, int resultCode, const QAndroidJniObject &data) = 0; + \fn void QAndroidActivityResultReceiver::handleActivityResult(int receiverRequestCode, int resultCode, const QAndroidJniObject &data) Reimplement this function to get activity results after starting an activity using either QtAndroid::startActivity() or QtAndroid::startIntentSender(). The \a receiverRequestCode is the request code unique to this receiver which was originally diff --git a/src/androidextras/android/qandroidservice.cpp b/src/androidextras/android/qandroidservice.cpp index 227787a..5359e0f 100644 --- a/src/androidextras/android/qandroidservice.cpp +++ b/src/androidextras/android/qandroidservice.cpp @@ -114,7 +114,11 @@ public: /*! - Creates a new Android Service + \fn QAndroidService::QAndroidService(int &argc, char **argv) + + Creates a new Android service, passing \a argc and \a argv as parameters. + + //! Parameter \a flags is omitted in the documentation. \sa QCoreApplication */ @@ -125,9 +129,14 @@ QAndroidService::QAndroidService(int &argc, char **argv, int flags) } /*! - Creates a new Android Service + \fn QAndroidService::QAndroidService(int &argc, char **argv, const std::function &binder) + + Creates a new Android service, passing \a argc and \a argv as parameters. + + \a binder is used to create a \l {QAndroidBinder}{binder} when needed. + + //! Parameter \a flags is omitted in the documentation. - \a binder is used to create a binder each when is needed \sa QCoreApplication */ QAndroidService::QAndroidService(int &argc, char **argv, const std::function &binder, int flags) diff --git a/src/androidextras/doc/QtAndroidExtras/QAndroidJniObject b/src/androidextras/doc/QtAndroidExtras/QAndroidJniObject new file mode 100644 index 0000000..b96916d --- /dev/null +++ b/src/androidextras/doc/QtAndroidExtras/QAndroidJniObject @@ -0,0 +1 @@ +#include "qandroidjniobject.h" diff --git a/src/androidextras/doc/QtAndroidExtras/jni.h b/src/androidextras/doc/QtAndroidExtras/jni.h new file mode 100644 index 0000000..01dbf0e --- /dev/null +++ b/src/androidextras/doc/QtAndroidExtras/jni.h @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part 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$ +** +****************************************************************************/ + +/* Dummy declarations passed to clang when generating the docs */ + +#ifndef JNI_H +#define JNI_H + +struct JNIEnv_; +typedef JNIEnv_ JNIEnv; +typedef int jclass; + +#endif diff --git a/src/androidextras/doc/QtAndroidExtras/qandroidextrasglobal.h b/src/androidextras/doc/QtAndroidExtras/qandroidextrasglobal.h new file mode 100644 index 0000000..9000f4e --- /dev/null +++ b/src/androidextras/doc/QtAndroidExtras/qandroidextrasglobal.h @@ -0,0 +1,2 @@ +#include "../../qandroidextrasglobal.h" +#include "QtCore/qvariant.h" diff --git a/src/androidextras/doc/QtAndroidExtras/qandroidjniobject.h b/src/androidextras/doc/QtAndroidExtras/qandroidjniobject.h new file mode 100644 index 0000000..7f58978 --- /dev/null +++ b/src/androidextras/doc/QtAndroidExtras/qandroidjniobject.h @@ -0,0 +1 @@ +#include "../../jni/qandroidjniobject.h" diff --git a/src/androidextras/doc/QtAndroidExtrasDoc b/src/androidextras/doc/QtAndroidExtrasDoc new file mode 100644 index 0000000..2294259 --- /dev/null +++ b/src/androidextras/doc/QtAndroidExtrasDoc @@ -0,0 +1,10 @@ +#include "qandroidextrasglobal.h" +#include "qandroidactivityresultreceiver.h" +#include "qandroidbinder.h" +#include "qandroidfunctions.h" +#include "qandroidintent.h" +#include "qandroidjnienvironment.h" +#include "qandroidjniobject.h" +#include "qandroidparcel.h" +#include "qandroidserviceconnection.h" +#include "qandroidservice.h" diff --git a/src/androidextras/doc/qtandroidextras.qdocconf b/src/androidextras/doc/qtandroidextras.qdocconf index b42a391..bf810ad 100644 --- a/src/androidextras/doc/qtandroidextras.qdocconf +++ b/src/androidextras/doc/qtandroidextras.qdocconf @@ -1,6 +1,16 @@ include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) Cpp.ignoretokens += Q_ANDROIDEXTRAS_EXPORT +# dummy module header for clang, found under doc/ +moduleheader = QtAndroidExtrasDoc + +# pass include paths to clang +includepaths += -I . \ + -I .. \ + -I ../android \ + -I ../jni \ + -I ./QtAndroidExtras \ + -I $QT_INSTALL_HEADERS project = QtAndroidExtras description = Qt Android Extras Reference Documentation diff --git a/src/androidextras/jni/qandroidjniobject.cpp b/src/androidextras/jni/qandroidjniobject.cpp index cee0260..8154a30 100644 --- a/src/androidextras/jni/qandroidjniobject.cpp +++ b/src/androidextras/jni/qandroidjniobject.cpp @@ -326,9 +326,9 @@ QAndroidJniObject::~QAndroidJniObject() } /*! - \fn T QAndroidJniObject::callMethod(const char *methodName, const char *signature, ...) const + \fn template T QAndroidJniObject::callMethod(const char *methodName, const char *sig, ...) const - Calls the method \a methodName with \a signature and returns the value. + Calls the method \a methodName with a signature \a sig and returns the value. \code QAndroidJniObject myJavaString = ...; @@ -338,7 +338,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::callMethod(const char *methodName) const + \fn template T QAndroidJniObject::callMethod(const char *methodName) const Calls the method \a methodName and returns the value. @@ -374,7 +374,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName) + \fn template T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName) Calls the static method \a methodName on \a clazz and returns the value. @@ -387,7 +387,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::callStaticMethod(const char *className, const char *methodName) + \fn template T QAndroidJniObject::callStaticMethod(const char *className, const char *methodName) Calls the static method \a methodName on class \a className and returns the value. @@ -397,7 +397,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::callStaticMethod(const char *className, const char *methodName, const char *signature, ...) + \fn template T QAndroidJniObject::callStaticMethod(const char *className, const char *methodName, const char *signature, ...) Calls the static method with \a methodName with \a signature on class \a className with optional arguments. @@ -411,7 +411,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName, const char *signature, ...) + \fn template T QAndroidJniObject::callStaticMethod(jclass clazz, const char *methodName, const char *signature, ...) Calls the static method \a methodName with \a signature on \a clazz and returns the value. @@ -547,7 +547,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn void QAndroidJniObject::setField(const char *fieldName, T value) + \fn template void QAndroidJniObject::setField(const char *fieldName, T value) Sets the value of \a fieldName to \a value. @@ -562,7 +562,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn void QAndroidJniObject::setField(const char *fieldName, const char *signature, T value) + \fn template void QAndroidJniObject::setField(const char *fieldName, const char *signature, T value) Sets the value of \a fieldName with \a signature to \a value. @@ -574,25 +574,25 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn void QAndroidJniObject::setStaticField(const char *className, const char *fieldName, T value) + \fn template void QAndroidJniObject::setStaticField(const char *className, const char *fieldName, T value) Sets the value of the static field \a fieldName in class \a className to \a value. */ /*! - \fn void QAndroidJniObject::setStaticField(const char *className, const char *fieldName, const char *signature, T value); + \fn template void QAndroidJniObject::setStaticField(const char *className, const char *fieldName, const char *signature, T value); Sets the static field with \a fieldName and \a signature to \a value on class \a className. */ /*! - \fn void QAndroidJniObject::setStaticField(jclass clazz, const char *fieldName, T value) + \fn template void QAndroidJniObject::setStaticField(jclass clazz, const char *fieldName, T value) Sets the static field \a fieldName of the class \a clazz to \a value. */ /*! - \fn void QAndroidJniObject::setStaticField(jclass clazz, const char *fieldName, const char *signature, T value); + \fn template void QAndroidJniObject::setStaticField(jclass clazz, const char *fieldName, const char *signature, T value); Sets the static field with \a fieldName and \a signature to \a value on class \a clazz. */ @@ -626,7 +626,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn T QAndroidJniObject::object() const + \fn template T QAndroidJniObject::object() const Returns the object held by the QAndroidJniObject as type T. @@ -650,7 +650,7 @@ QAndroidJniObject::~QAndroidJniObject() */ /*! - \fn QAndroidJniObject &QAndroidJniObject::operator=(T object) + \fn template QAndroidJniObject &QAndroidJniObject::operator=(T object) Replace the current object with \a object. The old Java object will be released. */ -- cgit v1.2.3