qdoc: Fix qdoc warnings from changes to QDtls

This update corrects several minor documentation errors that
were introduced by a recent change to QDtls.

Change-Id: I6ee6b0bf74c82dca86ba8d5f39acbd642829ec44
Reviewed-by: Timur Pocheptsov <timur.pocheptsov@qt.io>

3 files changed, 37 insertions, 23 deletions

diff --git a/src/network/ssl/qdtls.cpp b/src/network/ssl/qdtls.cpp
index e27bca51b9..7fc3a486a0 100644
--- a/src/network/ssl/qdtls.cpp
+++ b/src/network/ssl/qdtls.cpp
@@ -277,6 +277,12 @@
 */
 
 /*!
+    \typedef QDtls::GeneratorParameters
+
+    This is a synonym for QDtlsClientVerifier::GeneratorParameters.
+*/
+
+/*!
     \fn void QDtls::handshakeTimeout()
 
     Packet loss can result in timeouts during the handshake phase. In this case
@@ -447,9 +453,10 @@ QDtlsClientVerifier::QDtlsClientVerifier(QObject *parent)
 }
 
 /*!
-    Sets the secret and cryptographic hash algorithm that this QDtlsClientVerifier
-    will use to generate cookies. If the new secret has size zero, this function
-    returns \c false and does not change the previous generator parameters.
+    Sets the secret and the cryptographic hash algorithm from \a params. This
+    QDtlsClientVerifier will use these to generate cookies. If the new secret
+    has size zero, this function returns \c false and does not change the
+    cookie generator parameters.
 
     \note The secret is supposed to be a cryptographically secure sequence of bytes.
 
@@ -481,11 +488,12 @@ QDtlsClientVerifier::GeneratorParameters QDtlsClientVerifier::cookieGeneratorPar
 }
 
 /*!
-    \a socket must be a valid pointer, \a dgram must be a non-empty datagram,
-    \a address cannot be null, broadcast, or multicast. This function returns
-    \c true if \a dgram contains a ClientHello message with a valid cookie.
-    If no matching cookie is found, verifyClient() will send a HelloVerifyRequest
-    message using \a socket and will return \c false.
+    \a socket must be a valid pointer, \a dgram must be a non-empty
+    datagram, \a address cannot be null, broadcast, or multicast.
+    \a port is the remote peer's port. This function returns \c true
+    if \a dgram contains a ClientHello message with a valid cookie.
+    If no matching cookie is found, verifyClient() will send a
+    HelloVerifyRequest message using \a socket and return \c false.
 
     The following snippet shows how a server application may check for errors:
 
@@ -556,7 +564,7 @@ QString QDtlsClientVerifier::dtlsErrorString() const
     \a mode is QSslSocket::SslServerMode for a server-side DTLS connection or
     QSslSocket::SslClientMode for a client.
 
-    \sa sslMode(), QSslSocket::SslSocket
+    \sa sslMode(), QSslSocket::SslMode
 */
 QDtls::QDtls(QSslSocket::SslMode mode, QObject *parent)
     : QObject(*new QDtlsPrivateOpenSSL, parent)
@@ -568,9 +576,9 @@ QDtls::QDtls(QSslSocket::SslMode mode, QObject *parent)
 }
 
 /*!
-    Sets the peer's address, \a port, and host name. \a address must not be
-    null, multicast, or broadcast. \a verificationName is the host name used
-    for the certificate validation.
+    Sets the peer's address, \a port, and host name and returns \c true
+    if successful. \a address must not be null, multicast, or broadcast.
+    \a verificationName is the host name used for the certificate validation.
 
     \sa peerAddress(), peerPort(), peerVerificationName()
  */
@@ -607,7 +615,9 @@ bool QDtls::setPeer(const QHostAddress &address, quint16 port,
 }
 
 /*!
-    Sets the host name that will be used for the certificate validation.
+    Sets the host \a name that will be used for the certificate validation
+    and returns \c true if successful.
+
     \note This function must be called before the handshake starts.
 
     \sa peerVerificationName(), setPeer()
@@ -704,8 +714,9 @@ quint16 QDtls::mtuHint() const
 }
 
 /*!
-    Sets the cryptographic hash algorithm and the secret. This function is only
-    needed for a server-side QDtls connection.
+    Sets the cryptographic hash algorithm and the secret from \a params.
+    This function is only needed for a server-side QDtls connection.
+    Returns \c true if successful.
 
     \note This function must be called before the handshake starts.
 
@@ -738,7 +749,8 @@ QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const
 }
 
 /*!
-    Sets the connection's TLS configuration from \a configuration.
+    Sets the connection's TLS configuration from \a configuration
+    and returns \c true if successful.
 
     \note This function must be called before the handshake starts.
 
@@ -892,8 +904,10 @@ bool QDtls::continueHandshake(QUdpSocket *socket, const QByteArray &datagram)
 }
 
 /*!
-    If peer verification errors were ignored during the handshake, resumeHandshake()
-    resumes and completes the handshake. \a socket must be a valid pointer.
+    If peer verification errors were ignored during the handshake,
+    resumeHandshake() resumes and completes the handshake and returns
+    \c true. \a socket must be a valid pointer. Returns \c false if
+    the handshake could not be resumed.
 
     \sa doHandshake(), abortHandshake() peerVerificationErrors(), ignoreVerificationErrors()
 */
@@ -919,7 +933,7 @@ bool QDtls::resumeHandshake(QUdpSocket *socket)
     Aborts the handshake in case peer verification errors could not be ignored.
     \a socket must be a valid pointer.
 
-    \sa doHandshake(), resumeHandshakeAfterError()
+    \sa doHandshake(), resumeHandshake()
  */
 bool QDtls::abortHandshake(QUdpSocket *socket)
 {
@@ -1021,7 +1035,7 @@ QSsl::SslProtocol QDtls::sessionProtocol() const
     before writing encrypted data. \a socket must be a valid
     pointer.
 
-    \sa doHandshake(), handshakeState(), connectionEncrypted(), dtlsError()
+    \sa doHandshake(), handshakeState(), isConnectionEncrypted(), dtlsError()
 */
 qint64 QDtls::writeDatagramEncrypted(QUdpSocket *socket, const QByteArray &dgram)
 {
@@ -1107,7 +1121,7 @@ QVector<QSslError> QDtls::peerVerificationErrors() const
 }
 
 /*!
-    This method tells QDtls to ignore only the errors given in \a errors.
+    This method tells QDtls to ignore only the errors given in \a errorsToIgnore.
 
     If, for instance, you want to connect to a server that uses a self-signed
     certificate, consider the following snippet:
diff --git a/src/network/ssl/qsslconfiguration.cpp b/src/network/ssl/qsslconfiguration.cpp
index 12fbb9a8e4..df5660d4c3 100644
--- a/src/network/ssl/qsslconfiguration.cpp
+++ b/src/network/ssl/qsslconfiguration.cpp
@@ -1031,7 +1031,7 @@ void QSslConfiguration::setDefaultConfiguration(const QSslConfiguration &configu
     QSslConfigurationPrivate::setDefaultConfiguration(configuration);
 }
 
-#if QT_CONFIG(dtls)
+#if QT_CONFIG(dtls) || defined(Q_CLANG_QDOC)
 
 /*!
   This function returns true if DTLS cookie verification was enabled on a
diff --git a/src/network/ssl/qsslconfiguration.h b/src/network/ssl/qsslconfiguration.h
index 7f6028db27..454ac0cee3 100644
--- a/src/network/ssl/qsslconfiguration.h
+++ b/src/network/ssl/qsslconfiguration.h
@@ -162,7 +162,7 @@ public:
     static QSslConfiguration defaultConfiguration();
     static void setDefaultConfiguration(const QSslConfiguration &configuration);
 
-#if QT_CONFIG(dtls)
+#if QT_CONFIG(dtls) || defined(Q_CLANG_QDOC)
     bool dtlsCookieVerificationEnabled() const;
     void setDtlsCookieVerificationEnabled(bool enable);