Document QJSEngine's lack of exception handling API

Since we consider throwing non-Error values an edge case, we decided
not to add a an exception handling API (like
QScriptEngine::hasUncaughtException() or v8::TryCatch) yet.
Document this limitation in QJSEngine::evaluate().

Task-number: QTBUG-25857
Change-Id: I7f4869a152f176e613e3e8d2f81efeae198bd560
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@nokia.com>
Reviewed-by: Simon Hausmann <simon.hausmann@nokia.com>

1 files changed, 7 insertions, 3 deletions

diff --git a/src/qml/qml/v8/qjsengine.cpp b/src/qml/qml/v8/qjsengine.cpp
index 2bc4ffca7c..9791379652 100644
--- a/src/qml/qml/v8/qjsengine.cpp
+++ b/src/qml/qml/v8/qjsengine.cpp
@@ -229,9 +229,8 @@ void QJSEngine::collectGarbage()
 
     The evaluation of \a program can cause an exception in the
     engine; in this case the return value will be the exception
-    that was thrown (typically an \c{Error} object). You can call
-    isError() on the return value to determine whether an exception
-    occurred.
+    that was thrown (typically an \c{Error} object; see
+    QJSValue::isError()).
 
     \a lineNumber is used to specify a starting line number for \a
     program; line number information reported by the engine that pertain
@@ -244,6 +243,11 @@ void QJSEngine::collectGarbage()
     \a fileName is used for error reporting. For example in error objects
     the file name is accessible through the "fileName" property if it's
     provided with this function.
+
+    \note If an exception was thrown and the exception value is not an
+    Error instance (i.e., QJSValue::isError() returns false), the
+    exception value will still be returned, but there is currently no
+    API for detecting that an exception did occur in this case.
 */
 QJSValue QJSEngine::evaluate(const QString& program, const QString& fileName, int lineNumber)
 {