aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTopi Reinio <topi.reinio@qt.io>2018-03-01 12:40:21 +0100
committerTopi Reiniƶ <topi.reinio@qt.io>2018-04-11 07:19:12 +0000
commitb36bf0b3eaa026e22a87865e106f54be6b520811 (patch)
tree61b10cdf1634851820465ffbf6724e9be6d7f071
parenta2157a9dd2ee4ed3e998654595544dadaf129fe8 (diff)
Doc: Fix documentation issues when using Clang-enabled QDocv5.11.0-beta4
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 <martin.smith@qt.io>
-rw-r--r--src/androidextras/android/qandroidactivityresultreceiver.cpp2
-rw-r--r--src/androidextras/android/qandroidservice.cpp15
-rw-r--r--src/androidextras/doc/QtAndroidExtras/QAndroidJniObject1
-rw-r--r--src/androidextras/doc/QtAndroidExtras/jni.h49
-rw-r--r--src/androidextras/doc/QtAndroidExtras/qandroidextrasglobal.h2
-rw-r--r--src/androidextras/doc/QtAndroidExtras/qandroidjniobject.h1
-rw-r--r--src/androidextras/doc/QtAndroidExtrasDoc10
-rw-r--r--src/androidextras/doc/qtandroidextras.qdocconf10
-rw-r--r--src/androidextras/jni/qandroidjniobject.cpp30
9 files changed, 101 insertions, 19 deletions
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<QAndroidBinder *(const QAndroidIntent &)> &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<QAndroidBinder *(const QAndroidIntent &)> &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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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 <typename T> QAndroidJniObject &QAndroidJniObject::operator=(T object)
Replace the current object with \a object. The old Java object will be released.
*/