1 files changed, 43 insertions, 3 deletions

diff --git a/src/webengine/api/qquickwebenginenewviewrequest.cpp b/src/webengine/api/qquickwebenginenewviewrequest.cpp
index f2a361f55..053fcd2f6 100644
--- a/src/webengine/api/qquickwebenginenewviewrequest.cpp
+++ b/src/webengine/api/qquickwebenginenewviewrequest.cpp
@@ -39,6 +39,18 @@
 #include "qquickwebengineview_p_p.h"
 #include "web_contents_adapter.h"
 
+/*!
+    \qmltype WebEngineNewViewRequest
+    \instantiates QQuickWebEngineNewViewRequest
+    \inqmlmodule QtWebEngine 1.1
+    \since QtWebEngine 1.1
+
+    \brief A utility class for the WebEngineView::newViewRequested signal.
+
+    This class contains information about the request of a page to open a new window.
+
+    \sa WebEngineView::newViewRequested
+*/
 QQuickWebEngineNewViewRequest::QQuickWebEngineNewViewRequest()
 {
 }
@@ -47,20 +59,48 @@ QQuickWebEngineNewViewRequest::~QQuickWebEngineNewViewRequest()
 {
 }
 
+/*!
+    \qmlproperty WebEngineView::NewViewDestination WebEngineNewViewRequest::destination
+    \brief The type of view that is requested by the page.
+ */
 QQuickWebEngineView::NewViewDestination QQuickWebEngineNewViewRequest::destination() const
 {
     return m_destination;
 }
 
+/*!
+    \qmlproperty bool WebEngineNewViewRequest::isUserInitiated
+    \brief Whether this window request was directly triggered as the result of a keyboard or mouse event.
+
+    Use this property to block possibly unwanted "popups".
+ */
 bool QQuickWebEngineNewViewRequest::isUserInitiated() const
 {
     return m_isUserInitiated;
 }
 
+/*!
+    \qmlmethod WebEngineNewViewRequest::openIn(WebEngineView view)
+
+    Call this method to fulfill the request and determine which WebEngineView
+    should be used to contain the new page. Any state, history or loaded page
+    within \a view will be lost as result of this.
+
+    \sa WebEngineView::newViewRequested
+  */
 void QQuickWebEngineNewViewRequest::openIn(QQuickWebEngineView *view)
 {
-    if (view) {
-        view->d_func()->adoptWebContents(m_adapter.data());
-        m_adapter.reset();
+    if (!m_adapter) {
+        qWarning("Trying to open an empty request, it was either already used or was invalidated."
+            "\nYou must complete the request synchronously within the newViewRequested signal handler."
+            " If a view hasn't been adopted before returning, the request will be invalidated.");
+        return;
+    }
+
+    if (!view) {
+        qWarning("Trying to open a WebEngineNewViewRequest in an invalid WebEngineView.");
+        return;
     }
+    view->d_func()->adoptWebContents(m_adapter.data());
+    m_adapter.reset();
 }