From 252be0e10e66fd4d92bd59b0cf4de02a8084f5ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Str=C3=B8mme?= <christian.stromme@digia.com>
Date: Mon, 23 Sep 2013 16:13:42 +0200
Subject: [PATCH] Improve documentation.
Change-Id: Ia3999f853aa9b0ca1678f322419ddd200cae4b1a
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@digia.com>
---
src/androidextras/androidextras.pro | 2 +-
.../src_androidextras_qjnienvironment.cpp | 13 ++
.../code/src_androidextras_qjniobject.cpp | 13 ++
.../doc/src/qtandroidextras-index.qdoc | 20 ++-
.../doc/src/qtandroidextras-module.qdoc | 16 +-
src/androidextras/jni/qjnienvironment.cpp | 40 +++++
src/androidextras/jni/qjniobject.cpp | 158 ++++++++++--------
7 files changed, 191 insertions(+), 71 deletions(-)
diff --git a/src/androidextras/androidextras.pro b/src/androidextras/androidextras.pro
index fa89194..f3caeea 100644
--- a/src/androidextras/androidextras.pro
+++ b/src/androidextras/androidextras.pro
@@ -1,6 +1,6 @@
TARGET = QtAndroidExtras
DEFINES += QT_NO_USING_NAMESPACE
-#QMAKE_DOCS = $$PWD/doc/qtandroidextras.qdocconf
+QMAKE_DOCS = $$PWD/doc/qtandroidextras.qdocconf
QT -= gui
QT += core-private
load(qt_module)
diff --git a/src/androidextras/doc/snippets/code/src_androidextras_qjnienvironment.cpp b/src/androidextras/doc/snippets/code/src_androidextras_qjnienvironment.cpp
index e799420..bf1bd28 100644
--- a/src/androidextras/doc/snippets/code/src_androidextras_qjnienvironment.cpp
+++ b/src/androidextras/doc/snippets/code/src_androidextras_qjnienvironment.cpp
@@ -37,3 +37,16 @@
** $QT_END_LICENSE$
**
****************************************************************************/
+
+//! [Create QJNIEnvironment]
+
+bool exceptionCheck()
+{
+ /*
+ The QJNIEnvironment attaches the current thread to the JavaVM on
+ creation and detach when it goes out of scope.
+ */
+ QJNIEnvironment qjniEnv;
+ return qjniEnv->ExceptionCheck();
+}
+//! [Create QJNIEnvironment]
diff --git a/src/androidextras/doc/snippets/code/src_androidextras_qjniobject.cpp b/src/androidextras/doc/snippets/code/src_androidextras_qjniobject.cpp
index 1ef86fe..8be1053 100644
--- a/src/androidextras/doc/snippets/code/src_androidextras_qjniobject.cpp
+++ b/src/androidextras/doc/snippets/code/src_androidextras_qjniobject.cpp
@@ -68,3 +68,16 @@ void function()
// Ops! myJString is no longer valid.
}
//! [QJNIObject scope]
+
+//! [Check for exceptions]
+void function()
+{
+ QJNIObject myString = QJNIObject::fromString("Hello");
+ jchar c = myString.callMethod<jchar>("charAt", "(I)C", 1000);
+ QJNIEnvironment env;
+ if (env->ExceptionCheck()) {
+ // Handle exception here.
+ env->ExceptionClear();
+ }
+}
+//! [Check for exceptions]
diff --git a/src/androidextras/doc/src/qtandroidextras-index.qdoc b/src/androidextras/doc/src/qtandroidextras-index.qdoc
index 823e71e..cf7d3df 100644
--- a/src/androidextras/doc/src/qtandroidextras-index.qdoc
+++ b/src/androidextras/doc/src/qtandroidextras-index.qdoc
@@ -33,8 +33,24 @@
\section1 Getting Started
- \list
+ To include the definitions of the module's classes, use the
+ following directive:
- \endlist
+ \code
+ #include <QtAndroidExtras>
+ \endcode
+
+ To link against the module, add this line to your \l qmake \c
+ .pro file:
+
+ \code
+ QT += androidextras
+ \endcode
+ \section1 API Reference
+
+ Links to the API reference materials:
+ \list
+ \li \l{Qt Android Extras C++ Classes}{C++ Classes}
+ \endlist
*/
diff --git a/src/androidextras/doc/src/qtandroidextras-module.qdoc b/src/androidextras/doc/src/qtandroidextras-module.qdoc
index f62484e..badb8a7 100644
--- a/src/androidextras/doc/src/qtandroidextras-module.qdoc
+++ b/src/androidextras/doc/src/qtandroidextras-module.qdoc
@@ -28,10 +28,22 @@
/*!
\module QtAndroidExtras
\title Qt Android Extras C++ Classes
- \brief The Qt Android Extras module contains functionality to additional functionality to aid development on Android.
+ \brief The Qt Android Extras module contains additional functionality for development on Android.
\ingroup modules
\qtvariable androidextras
- The Qt Android Extras module adds...
+ To include the definitions of the module's classes, use the
+ following directive:
+
+ \code
+ #include <QtAndroidExtras>
+ \endcode
+
+ To link against the module, add this line to your \l qmake \c
+ .pro file:
+
+ \code
+ QT += androidextras
+ \endcode
*/
diff --git a/src/androidextras/jni/qjnienvironment.cpp b/src/androidextras/jni/qjnienvironment.cpp
index f21d763..e27e5ce 100644
--- a/src/androidextras/jni/qjnienvironment.cpp
+++ b/src/androidextras/jni/qjnienvironment.cpp
@@ -46,6 +46,46 @@
QT_BEGIN_NAMESPACE
+/*!
+ \class QJNIEnvironment
+ \inmodule QtAndroidExtras
+ \brief The QJNIEnvironment provides access to the JNI Environment.
+ \since 5.2
+*/
+
+/*!
+ \fn QJNIEnvironment::QJNIEnvironment()
+
+ Constructs a new QJNIEnvironment object and attach the current thread to the Java VM.
+
+ \snippet code/src_androidextras_qjnienvironment.cpp Create QJNIEnvironment
+*/
+
+/*!
+ \fn QJNIEnvironment::~QJNIEnvironment()
+
+ Detaches the current thread from the Java VM and destroys the QJNIEnvironment object.
+*/
+
+/*!
+ \fn JavaVM *QJNIEnvironment::javaVM()
+
+ Returns the Java VM interface.
+*/
+
+/*!
+ \fn JNIEnv *QJNIEnvironment::operator->()
+
+ Provides access to the QJNIEnvironment's JNIEnv pointer.
+*/
+
+/*!
+ \fn QJNIEnvironment::operator JNIEnv *() const
+
+ Returns the the JNI Environment pointer.
+ */
+
+
QJNIEnvironment::QJNIEnvironment()
: d(new QJNIEnvironmentPrivate)
{
diff --git a/src/androidextras/jni/qjniobject.cpp b/src/androidextras/jni/qjniobject.cpp
index e5dc6e5..8922de9 100644
--- a/src/androidextras/jni/qjniobject.cpp
+++ b/src/androidextras/jni/qjniobject.cpp
@@ -48,12 +48,14 @@ QT_BEGIN_NAMESPACE
/*!
\class QJNIObject
\inmodule QtAndroidExtras
- \brief The QJNIObject ...
+ \brief The QJNIObject is a C++ wrapper around a Java class.
\since 5.2
- \section1 Stub
+ QJNIObject provides APIs to call Java methods
- Supported JNI object types:
+ \section1 JNI types
+
+ Object types:
\list
\li jobject
\li jclass
@@ -70,7 +72,7 @@ QT_BEGIN_NAMESPACE
\li jdoubleArray
\endlist
- Supported JNI Primitive types:
+ Primitive types:
\list
\li jboolean
\li jbyte
@@ -82,21 +84,28 @@ QT_BEGIN_NAMESPACE
\li jdouble
\endlist
- About function types: ...
+ \section1 General Notes:
- - Class name strings needs to be the fully-qualified class name, e.g., "java/lang/String".
+ - Class name strings needs to be the fully-qualified class name, for example: "java/lang/String".
- Method signatures are written as "(Arguments)ReturnType"
- All object types are returned as a QJNIObject.
- More information about JNI can be found in the java doc [url]
+ \section1 Handling Java exception:
+
+ When calling Java functions that might throw an exception, it is important that you handle and
+ clear out the exception before continuing.
+
+ \snippet code/src_androidextras_qjniobject.cpp Check for exceptions
+ For more information about JNI see: \l http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html
*/
/*!
\fn QJNIObject::QJNIObject()
- \code
- \endcode
+ Constructs an invalid QJNIObject.
+
+ \sa isValid()
*/
/*!
@@ -143,10 +152,12 @@ QT_BEGIN_NAMESPACE
/*!
\fn QJNIObject::QJNIObject(jclass clazz, const char *signature, ...)
- Constructs a new QJNIObject from \a clazz by calling the non-default
- constructor with \a signature and arguments.
+ Constructs a new QJNIObject from \a clazz by calling the constructor with \a signature
+ and arguments.
\code
+ jclass myClass = ...;
+ QJNIObject::QJNIObject(myClazz, "(I)V", 3);
\endcode
*/
@@ -167,20 +178,25 @@ QT_BEGIN_NAMESPACE
*/
/*!
- \fn T QJNIObject::callMethod(const char *methodName) const
+ \fn T QJNIObject::callMethod(const char *methodName, const char *signature, ...) const
- Calls the Java object method \a methodName and returns the value.
+ Calls the method \a methodName with \a signature and returns the value.
\code
QJNIObject myJavaString = ...;
- jint size = myJavaString.callMethod<jint>("length");
+ jint index = myJavaString.callMethod<jint>("indexOf", "(I)I", 0x0051);
\endcode
+
*/
/*!
- \fn T QJNIObject::callMethod(const char *methodName, const char *signature, ...) const
+ \fn T QJNIObject::callMethod(const char *methodName) const
+
+ Calls the method \a methodName and returs the value.
\code
+ QJNIObject myJavaString = ...;
+ jint size = myJavaString.callMethod<jint>("length");
\endcode
*/
@@ -210,28 +226,38 @@ QT_BEGIN_NAMESPACE
*/
/*!
- \fn T QJNIObject::callStaticMethod(const char *className, const char *methodName)
+ \fn T QJNIObject::callStaticMethod(jclass clazz, const char *methodName)
+
+ Calls the static method \a methodName on \a clazz and returns the value T.
\code
+ ...
+ jclass javaMathClass = ...; // ("java/lang/Math")
+ jdouble randNr = QJNIObject::callStaticMethod<jdouble>(javaMathClass, "random");
+ ...
\endcode
*/
/*!
- \fn T QJNIObject::callStaticMethod(const char *className, const char *methodName, const char *sig, ...)
+ \fn T QJNIObject::callStaticMethod(const char *className, const char *methodName)
+
+ Calls the static method \a methodName on class \a className and returns the value.
\code
+ jint value = QJNIObject::callStaticMethod<jint>("MyClass", "staticMethod");
\endcode
*/
/*!
- \fn T QJNIObject::callStaticMethod(jclass clazz, const char *methodName)
+ \fn T QJNIObject::callStaticMethod(const char *className, const char *methodName, const char *signature, ...)
- Calls the static method \a methodName on \a clazz and returns the value T.
+ Calls the static method with \a methodName with \a signature on class \a className with optional arguments.
\code
...
- jclass javaMathClass = ...; // ("java/lang/Math")
- jdouble randNr = QJNIObject::callStaticMethod<jdouble>(javaMathClass, "random");
+ jint a = 2;
+ jint b = 4;
+ jint max = QJNIObject::callStaticMethod<jint>("java/lang/Math", "max", "(II)I", a, b);
...
\endcode
*/
@@ -255,105 +281,101 @@ QT_BEGIN_NAMESPACE
/*!
\fn QJNIObject QJNIObject::callStaticObjectMethod(const char *className, const char *methodName)
+ Calls the static method with \a methodName on the class \a className.
+
\code
+ QJNIObject string = QJNIObject::callStaticObjectMethod<jstring>("CustomClass", "getClassName");
\endcode
*/
/*!
- \fn QJNIObject QJNIObject::callStaticObjectMethod(const char *className, const char *methodName, const char *sig, ...)
+ \fn QJNIObject QJNIObject::callStaticObjectMethod(const char *className, const char *methodName, const char *signature, ...)
+
+ Calls the static method with \a methodName and \a signature on the class \a className.
\code
+ QJNIObject thread = QJNIObject::callStaticObjectMethod("java/lang/Thread", "currentThread", "()Ljava/lang/Thread;");
+ QJNIObject string = QJNIObject::callStaticObjectMethod("java/lang/String", "valueOf", "(I)Ljava/lang/String;", 10);
\endcode
*/
/*!
\fn QJNIObject QJNIObject::callStaticObjectMethod(jclass clazz, const char *methodName)
- Calls the static \e object method \a methodName on \a clazz.
- \code
- \endcode
+ Calls the static method with \a methodName on \a clazz.
+
*/
/*!
\fn QJNIObject QJNIObject::callStaticObjectMethod(jclass clazz, const char *methodName, const char *signature, ...)
- \code
- \endcode
+ Calls the static method with \a methodName and \a signature on class \a clazz.
*/
/*!
\fn T QJNIObject::getField(const char *fieldName) const
- \code
- \endcode
-*/
-
-/*!
- \fn T QJNIObject::getField(const char *fieldName, const char *sig) const
+ Retrieves the value of the field \a fieldName.
\code
+ QJNIObject volumeControll = ...;
+ jint fieldValue = obj.getField<jint>("MAX_VOLUME");
\endcode
*/
/*!
\fn QJNIObject QJNIObject::getObjectField(const char *fieldName) const
- \code
- \endcode
+ Retrieves the object of field \a fieldName.
*/
/*!
\fn QJNIObject QJNIObject::getObjectField(const char *fieldName, const char *signature) const
- \code
- \endcode
+ Retrieves the object from the field with \a signature and \a fieldName.
*/
/*!
\fn T QJNIObject::getStaticField(const char *className, const char *fieldName)
- \code
- \endcode
+ Retrieves the value from the static field \a fieldName on the class \a className.
*/
/*!
\fn T QJNIObject::getStaticField(jclass clazz, const char *fieldName)
- \code
- \endcode
+ Retrieves the value from the static field \a fieldName on \a clazz.
*/
/*!
\fn QJNIObject QJNIObject::getStaticObjectField(const char *className, const char *fieldName)
- \code
- \endcode
+ Retrieves the object from the field \a fieldName on the class \a className.
*/
/*!
\fn QJNIObject QJNIObject::getStaticObjectField(const char *className, const char *fieldName, const char *signature)
- \code
- \endcode
+ Retrieves the object from the field with \a signature and \a fieldName on class \a className.
*/
/*!
\fn QJNIObject QJNIObject::getStaticObjectField(jclass clazz, const char *fieldName)
- \code
- \endcode
+ Retrieves the object from the field \a fieldName on \a clazz.
*/
/*!
\fn QJNIObject QJNIObject::getStaticObjectField(jclass clazz, const char *fieldName, const char *signature)
- \code
- \endcode
+ Retrieves the object from the field with \a signature and \a fieldName on \a clazz.
*/
/*!
\fn void QJNIObject::setField(const char *fieldName, T value)
+ Sets the value of \a fieldName to \a value.
+
\code
...
QJNIObject obj;
@@ -367,36 +389,37 @@ QT_BEGIN_NAMESPACE
/*!
\fn void QJNIObject::setField(const char *fieldName, const char *signature, T value)
+ Sets the value of \a fieldName with \a signature to \a value.
+
\code
+ QJNIObject stringArray = ...;
+ QJNIObject obj = ...;
+ obj.setField<jobjectArray>("KEY_VALUES", "([Ljava/lang/String;)V", stringArray.object<jobjectArray>())
\endcode
*/
/*!
\fn void QJNIObject::setStaticField(const char *className, const char *fieldName, T value)
- \code
- \endcode
+ Sets the value of the static field \a fieldName in class \a className to \a value.
*/
/*!
- \fn void QJNIObject::setStaticField(const char *className, const char *fieldName, const char *sig, T value);
+ \fn void QJNIObject::setStaticField(const char *className, const char *fieldName, const char *signature, T value);
- \code
- \endcode
+ Sets the static field with \a fieldName and \a signature to \a value on class \a className.
*/
/*!
\fn void QJNIObject::setStaticField(jclass clazz, const char *fieldName, T value)
- \code
- \endcode
+ Sets the static field \a fieldName of the class \a clazz to \a value.
*/
/*!
- \fn void QJNIObject::setStaticField(jclass clazz, const char *fieldName, const char *sig, T value);
+ \fn void QJNIObject::setStaticField(jclass clazz, const char *fieldName, const char *signature, T value);
- \code
- \endcode
+ Sets the static field with \a fieldName and \a signature to \a value on class \a clazz.
*/
/*!
@@ -448,26 +471,27 @@ QT_BEGIN_NAMESPACE
\fn QJNIObject &QJNIObject::operator=(T object)
Replace the current object with \a object. The old Java object will be released.
-
- \code
- \endcode
*/
/*!
\fn QString QJNIObject::toString() const
- Returns a QString with the data returned from calling the toString() function on a java object.
- If the QJNIObject is wrapped around a Java String, calling this is a convenient way to convert
- a Java string to a QString.
+ Returns a QString with a string representation of the java object.
+ Calling this function on a Java String object is a convenient way of getting the actuall string
+ data.
\code
+ QJNIObject string = ...; // "Hello Java"
+ QString qstring = string.toString(); // "Hello Java"
\endcode
+
+ \sa fromString()
*/
/*!
\fn QJNIObject QJNIObject::fromString(const QString &string)
- Creates a Java string from the QString \a string and returns a QJNIObject wrapping that string.
+ Creates a Java string from the QString \a string and returns a QJNIObject holding that string.
\code
...
@@ -475,6 +499,8 @@ QT_BEGIN_NAMESPACE
QJNIObject myJavaString = QJNIObject::fromString(myQString);
...
\endcode
+
+ \sa toString()
*/
/*!
--
GitLab