Improve documentation about certificate errors

Documentation about how to handle certificate errors was poor,
so this patch try to improve that.

[ChangeLog][QtWebEngineQML][QQuickWebEngineCertificateError] New API for handling certificate errors in the QML API.

Change-Id: I9234f5c8296651e7634ee41827fc6dcce503398b
Reviewed-by: Michael Brüning <michael.bruning@theqtcompany.com>

3 files changed, 58 insertions, 4 deletions

diff --git a/src/webengine/api/qquickwebenginecertificateerror.cpp b/src/webengine/api/qquickwebenginecertificateerror.cpp
index a39bbfb84..010c66be5 100644
--- a/src/webengine/api/qquickwebenginecertificateerror.cpp
+++ b/src/webengine/api/qquickwebenginecertificateerror.cpp
@@ -58,8 +58,6 @@ public:
     bool answered;
 };
 
-
-
 /*!
     \qmltype WebEngineCertificateError
     \instantiates QQuickWebEngineCertificateError
@@ -71,7 +69,7 @@ public:
     This class contains information about a certificate error that happened and provides a way to accept or
     deny a certificate exception.
 
-    \sa WebEngineView::certificateError
+    \sa WebEngineCertificateError::certificateError
 */
 QQuickWebEngineCertificateError::QQuickWebEngineCertificateError(const QSharedPointer<CertificateErrorController> &controller, QObject *parent)
     : QObject(parent)
@@ -131,7 +129,9 @@ void QQuickWebEngineCertificateError::rejectCertificate()
 
 /*!
     \qmlproperty url WebEngineCertificateError::url
-    \brief The URL of the certificate error.
+    \readonly
+
+    The URL that triggered the error.
  */
 QUrl QQuickWebEngineCertificateError::url() const
 {
@@ -144,6 +144,23 @@ QUrl QQuickWebEngineCertificateError::url() const
 
 /*!
     \qmlproperty enumeration WebEngineCertificateError::error
+    \readonly
+
+    The type of the error.
+
+    \value SslPinnedKeyNotInCertificateChain The certificate did not match the built-in public key pins for the host name.
+    \value CertificateCommonNameInvalid The certificate's common name did not match the host name.
+    \value CertificateDateInvalid The certificate is not valid at the current date and time.
+    \value CertificateAuthorityInvalid The certificate is not signed by a trusted authority.
+    \value CertificateContainsErrors The certificate contains errors.
+    \value CertificateNoRevocationMechanism The certificate has no mechanism for determining if it has been revoked.
+    \value CertificateUnableToCheckRevocation Revocation information for the certificate is not available.
+    \value CertificateRevoked The certificate has been revoked.
+    \value CertificateInvalid The certificate is invalid.
+    \value CertificateWeakSignatureAlgorithm The certificate is signed using a weak signature algorithm.
+    \value CertificateNonUniqueName The host name specified in the certificate is not unique.
+    \value CertificateWeakKey The certificate contains a weak key.
+    \value CertificateNameConstraintViolation The certificate claimed DNS names that are in violation of name constraints.
 */
 QQuickWebEngineCertificateError::Error QQuickWebEngineCertificateError::error() const
 {
@@ -153,6 +170,9 @@ QQuickWebEngineCertificateError::Error QQuickWebEngineCertificateError::error()
 
 /*!
     \qmlproperty string WebEngineCertificateError::description
+    \readonly
+
+    A short localized human-readable description of the error.
 */
 QString QQuickWebEngineCertificateError::description() const
 {
@@ -162,6 +182,9 @@ QString QQuickWebEngineCertificateError::description() const
 
 /*!
     \qmlproperty bool WebEngineCertificateError::overridable
+    \readonly
+
+    A boolean that indicates if the certificate error can be overridden and accepted.
 */
 bool QQuickWebEngineCertificateError::overridable() const
 {
diff --git a/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc
index 5179f31b8..6d04473d3 100644
--- a/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc
+++ b/src/webengine/doc/src/qquickwebengineview_lgpl.qdoc
@@ -301,6 +301,26 @@
 */
 
 /*!
+    \qmlsignal WebEngineView::certificateError(error)
+
+    This signal is emitted when an invalid certificate error is raised while loading a given request.
+
+    The certificate error can be rejected by calling WebEngineCertificateError::rejectCertificate,
+    which will stop loading the request.
+
+    The certificate error can be ignored  by calling WebEngineCertificateError::ignoreCertificateError
+    which will resume loading the request.
+
+    It is possible to defer the decision of rejecting the given certificate by calling
+    WebEngineCertificateError::defer, which is useful when waiting for user input.
+    By default the invalid certificate will be automatically rejected.
+
+    The corresponding handler is onCertificateError.
+
+    \sa WebEngineCertificateError
+*/
+
+/*!
     \qmlsignal WebEngineView::linkHovered(hoveredUrl)
 
     Within a mouse-driven interface, this signal is emitted when a mouse
diff --git a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
index f5aa64eed..3088a66b6 100644
--- a/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
+++ b/src/webenginewidgets/doc/src/qwebenginepage_lgpl.qdoc
@@ -346,6 +346,17 @@
 */
 
 /*!
+    \fn bool QWebEnginePage::certificateError(const QWebEngineCertificateError & certificateError)
+    This function is called when an invalid certificate error is raised while loading a given request.
+
+    The \a certificateError parameter contains information about the certificate and details of the error.
+
+    Return true to ignore the error and complete the request, otherwise return false to stop loading the request.
+
+    \sa QWebEngineCertificateError
+*/
+
+/*!
     \fn QString QWebEnginePage::chooseFiles(FileSelectionMode mode, const QStringList& oldFiles, const QStringList& acceptedMimeTypes)
     This function is called when the web content requests a file name, for example
     as a result of the user clicking on a "file upload" button in a HTML form.