1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Fix template information for QJniObject members

Browse Source 
When QDoc parses a project, it parses the source code to extract the
user-provided documentation and perform sanity checkings based on the
code itself on it.

When QDoc parses an "\fn" command as part of this process, it tries to
understand, based on its intermediate representation built on the
information extracted from the code-base, which "documentable element"
the "\fn" refers to.

When QDoc performs this "matching" process, it takes into consideration
only a certain amount of information.
For example, no checking is performed over the template declaration of a
callable.

Due to some upcoming documentation, where two callables are
indistinguishable to the current process, as they differ only in their
template declaration, QDoc will start to take into consideration the
template declaration of a callable when matching.

This implies that an "\fn" command should now provide information
parity, with regards to template declaration for callables, with the
code-base so that QDoc can perform the match correctly.

The documentation for some of the members of `QJniObject` is not in sync
with the intended target template declaration.

Hence, add the missing information to the relevant "\fn" commands.

An additional `\fn` command was added for `jobject
QJniObject::object()`.
`object` has two overloads that are only distinguishable by their
template declaration, where the `jobject` returning overload has none
and the `T` overload has a template declaration.

The only documented overload was the templated version, but due to QDoc
not considering template information it was incorrectly being matched to
the non templated version.

Now that template information are taken into consideration, the provided
documentation correctly matches the templated version and the non
templated version was left undocumented.

The documentation block for the templated version is documented so that
both versions are covered by it.

Hence, an `\fn` command for the non templated version was added to the
documentation block for the templated version.

Task-number: QTBUG-118080
Change-Id: Ib77603bae99fdebbeec5d012a6c671246f4f2d1e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This commit is contained in:
Luca Di Sera 2023-11-10 13:49:36 +01:00
parent d3001d8a35
commit ac9fdf36b0
1 changed files with 8 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
src/corelib/kernel/qjniobject.cpp
View File

@ -803,6 +803,7 @@ JNIEnv *QJniObject::jniEnv() const noexcept
}
/*!
\fn jobject QJniObject::object() const
\fn template <typename T> T QJniObject::object() const
Returns the object held by the QJniObject either as jobject or as type T.
@ -1141,7 +1142,7 @@ QJniObject QJniObject::callStaticObjectMethod(jclass clazz, jmethodID methodId,
*/
/*!
\fn template <typename T> QJniObject &QJniObject::operator=(T object)
\fn template <typename T, std::enable_if_t<std::is_convertible_v<T, jobject>, bool> = true> QJniObject &QJniObject::operator=(T object)
Replace the current object with \a object. The old Java object will be released.
*/
@ -1162,7 +1163,7 @@ QJniObject QJniObject::callStaticObjectMethod(jclass clazz, jmethodID methodId,
*/
/*!
\fn T QJniObject::getField(const char *fieldName) const
\fn template<typename T> T QJniObject::getField(const char *fieldName) const
Retrieves the value of the field \a fieldName.
@ -1173,13 +1174,13 @@ QJniObject QJniObject::callStaticObjectMethod(jclass clazz, jmethodID methodId,
*/
/*!
\fn T QJniObject::getStaticField(const char *className, const char *fieldName)
\fn template<typename T> T QJniObject::getStaticField(const char *className, const char *fieldName)
Retrieves the value from the static field \a fieldName on the class \a className.
*/
/*!
\fn T QJniObject::getStaticField(jclass clazz, const char *fieldName)
\fn template<typename T> T QJniObject::getStaticField(jclass clazz, const char *fieldName)
Retrieves the value from the static field \a fieldName on \a clazz.
*/
@ -1277,7 +1278,7 @@ QJniObject QJniObject::getStaticObjectField(jclass clazz, const char *fieldName,
*/
/*!
\fn QJniObject QJniObject::getObjectField(const char *fieldName) const
\fn template<typename T> QJniObject QJniObject::getObjectField(const char *fieldName) const
Retrieves a JNI object from the field \a fieldName.
@ -1320,7 +1321,7 @@ QJniObject QJniObject::getObjectField(const char *fieldName, const char *signatu
*/
/*!
\fn QJniObject QJniObject::getStaticObjectField(const char *className, const char *fieldName)
\fn template<typename T> QJniObject QJniObject::getStaticObjectField(const char *className, const char *fieldName)
Retrieves the object from the field \a fieldName on the class \a className.
@ -1330,7 +1331,7 @@ QJniObject QJniObject::getObjectField(const char *fieldName, const char *signatu
*/
/*!
\fn QJniObject QJniObject::getStaticObjectField(jclass clazz, const char *fieldName)
\fn template<typename T> QJniObject QJniObject::getStaticObjectField(jclass clazz, const char *fieldName)
Retrieves the object from the field \a fieldName on \a clazz.