Clarify documentation about throwError and the specific error types

Elaborate a bit on some specific types, suggest the use of the overload
and omit some values that either exist only to complete the enum for API
standard purposes (NoError) or exist only for porting purposes but are
not relevant in use (EvalError).

Change-Id: I4f9cf7a4605305642fc20570a90a16f2c29d8b98
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Reviewed-by: Richard Weickelt <richard@weickelt.de>

2 files changed, 22 insertions, 6 deletions

diff --git a/src/qml/jsapi/qjsengine.cpp b/src/qml/jsapi/qjsengine.cpp
index 3bde6a60c4..aab72f8b2d 100644
--- a/src/qml/jsapi/qjsengine.cpp
+++ b/src/qml/jsapi/qjsengine.cpp
@@ -927,6 +927,10 @@ bool QJSEngine::convertV2(const QJSValue &value, int type, void *ptr)
     }
     \endcode
 
+    If you need a more specific run-time error to describe an exception, you can use the
+    \l {QJSEngine::}{throwError(QJSValue::ErrorType errorType, const QString &message)}
+    overload.
+
     \since Qt 5.12
     \sa {Script Exceptions}
 */
@@ -936,6 +940,8 @@ void QJSEngine::throwError(const QString &message)
 }
 
 /*!
+    \overload throwError()
+
     Throws a run-time error (exception) with the given \a errorType and
     \a message.
 
diff --git a/src/qml/jsapi/qjsvalue.cpp b/src/qml/jsapi/qjsvalue.cpp
index 14baf0ac10..b3ae630a95 100644
--- a/src/qml/jsapi/qjsvalue.cpp
+++ b/src/qml/jsapi/qjsvalue.cpp
@@ -163,16 +163,26 @@
     \enum QJSValue::ErrorType
     \since 5.12
 
-    This enum is used to specify a type of Error object.
+    Use this enum for JavaScript language-specific types of Error objects.
 
-    \value NoError Not an Error object.
+    They may be useful when emulating language features in C++ requires the use
+    of specialized exception types. In addition, they may help to more clearly
+    communicate certain typical conditions, instead of throwing a generic
+    JavaScript exception. For example, code that deals with networking and
+    resource locators may find it useful to propagate errors related to
+    malformed locators using the URIError type.
+
+    \omitvalue NoError
     \value GenericError A generic Error object, but not of a specific sub-type.
-    \value EvalError An error regarding the global eval() function.
+    \omitvalue EvalError
     \value RangeError A value did not match the expected set or range.
     \value ReferenceError A non-existing variable referenced.
-    \value SyntaxError Invalid syntax.
-    \value TypeError A value did not match the expected type.
-    \value URIError A URI handling function was used incorrectly.
+    \value SyntaxError An invalid token or sequence of tokens was encountered
+    that does not conform with the syntax of the language.
+    \value TypeError An operand or argument is incompatible with the type
+    expected.
+    \value URIError A URI handling function was used incorrectly or the URI
+    provided is malformed.
 */
 
 QT_BEGIN_NAMESPACE