From 23d7d5627391be1ad5a13ec6f6ec3fc8db2b1c93 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Tue, 14 Aug 2018 12:27:41 +0200 Subject: [PATCH] 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 --- src/network/ssl/qdtls.cpp | 56 +++++++++++++++++---------- src/network/ssl/qsslconfiguration.cpp | 2 +- src/network/ssl/qsslconfiguration.h | 2 +- 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 @@ -276,6 +276,12 @@ \sa QUdpSocket, QDtlsClientVerifier, HandshakeState, QDtlsError, QSslConfiguration */ +/*! + \typedef QDtls::GeneratorParameters + + This is a synonym for QDtlsClientVerifier::GeneratorParameters. +*/ + /*! \fn void QDtls::handshakeTimeout() @@ -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 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);