Improved documentation of evaluateJavaScript().

Change-Id: I47d8f4c0e392ffb70655db9725b035d22a7cad91
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@theqtcompany.com>

2 files changed, 24 insertions, 2 deletions

diff --git a/Source/WebKit/qt/Api/qwebelement.cpp b/Source/WebKit/qt/Api/qwebelement.cpp
index 26aedc1f5..8f54d4abc 100644
--- a/Source/WebKit/qt/Api/qwebelement.cpp
+++ b/Source/WebKit/qt/Api/qwebelement.cpp
@@ -740,7 +740,14 @@ static bool setupScriptContext(WebCore::Element* element, ScriptState*& state, S
 }
 
 /*!
-    Executes \a scriptSource with this element as \c this object.
+    Executes \a scriptSource with this element as \c this object
+    and returns the result of the last executed statement.
+
+    \note This method may be very inefficient if \a scriptSource returns
+    a DOM element as a result. See \l{QWebFrame::evaluateJavaScript()}
+    for more details.
+
+    \sa QWebFrame::evaluateJavaScript()
 */
 QVariant QWebElement::evaluateJavaScript(const QString& scriptSource)
 {
diff --git a/Source/WebKit/qt/WidgetApi/qwebframe.cpp b/Source/WebKit/qt/WidgetApi/qwebframe.cpp
index e8faab881..38c649887 100644
--- a/Source/WebKit/qt/WidgetApi/qwebframe.cpp
+++ b/Source/WebKit/qt/WidgetApi/qwebframe.cpp
@@ -910,7 +910,22 @@ void QWebFrame::print(QPrinter *printer) const
     Evaluates the JavaScript defined by \a scriptSource using this frame as context
     and returns the result of the last executed statement.
 
-    \sa addToJavaScriptWindowObject(), javaScriptWindowObjectCleared()
+    \note This method may be very inefficient if \a scriptSource returns
+
+    For example, evaluation of the next innocuously looking code may take a lot
+    of CPU and memory to execute:
+
+    \code
+        var img = document.createElement('img');
+        document.getElementById(\"foo\").appendChild(img);
+    \endcode
+
+    This code returns appended DOM element, which is converted to QVariantMap
+    containing all its properties. To avoid this issue you can add "true" after
+    the last statement.
+
+    \sa addToJavaScriptWindowObject(), javaScriptWindowObjectCleared(),
+    QWebElement::evaluateJavaScript()
 */
 QVariant QWebFrame::evaluateJavaScript(const QString& scriptSource)
 {