Improve the documentation and fix warnings

Change-Id: I9b26337ba976079608ece4781999ad0ef49a4f19
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

11 files changed, 219 insertions, 109 deletions

diff --git a/src/coap/qcoapclient.cpp b/src/coap/qcoapclient.cpp
index 34608c1..e4fd763 100644
--- a/src/coap/qcoapclient.cpp
+++ b/src/coap/qcoapclient.cpp
@@ -62,6 +62,8 @@ QCoapClientPrivate::~QCoapClientPrivate()
 
 /*!
     \class QCoapClient
+    \inmodule QtCoap
+
     \brief The QCoapClient class allows the application to
     send CoAP requests and receive replies.
 
@@ -82,17 +84,16 @@ QCoapClientPrivate::~QCoapClientPrivate()
         client->get(QCoapRequest(Qurl("coap://coap.me/test")));
     \endcode
 
-    \note After the request has finished, it is the responsibility of the user
-    to delete the QCoapReply object at an appropriate time. Do not directly
-    delete it inside the slot connected to finished(). You can use the
+    \note After processing of the request has finished, it is the responsibility
+    of the user to delete the QCoapReply object at an appropriate time. Do not
+    directly delete it inside the slot connected to finished(). You can use the
     deleteLater() function.
 
-    You can also use an "observe" request. This can be used as above, or more
-    conveniently with the \l{QCoapReply::notified(const QByteArray&)}{notified(const QByteArray&)}
-    signal:
+    You can also use an \e observe request. This can be used as above, or more
+    conveniently with the QCoapReply::notified() signal:
     \code
         QCoapRequest request = QCoapRequest(Qurl("coap://coap.me/obs"));
-        CoapReply *reply = client->observe(request);
+        QCoapReply *reply = client->observe(request);
         connect(reply, &QCoapReply::notified, this, &TestClass::slotNotified);
     \endcode
 
@@ -101,7 +102,7 @@ QCoapClientPrivate::~QCoapClientPrivate()
         client->cancelObserve(reply);
     \endcode
 
-    When a reply arrives, the QCoapClient emits a finished(QCoapReply *) signal.
+    When a reply arrives, the QCoapClient emits a finished() signal.
 
     \note For a discovery request, the returned object is a QCoapDiscoveryReply.
     It can be used the same way as a QCoapReply but contains also a list of
@@ -113,10 +114,10 @@ QCoapClientPrivate::~QCoapClientPrivate()
 /*!
     \fn void QCoapClient::finished(QCoapReply *reply)
 
-    This signal is emitted along with the \l{QCoapReply::finished()} signal
-    whenever a CoAP reply is finished, after either a success or an error.
+    This signal is emitted along with the \l QCoapReply::finished() signal
+    whenever a CoAP reply is received, after either a success or an error.
     The \a reply parameter will contain a pointer to the reply that has just
-    finished.
+    been received.
 
     \sa error(), QCoapReply::finished(), QCoapReply::error()
 */
@@ -136,7 +137,8 @@ QCoapClientPrivate::~QCoapClientPrivate()
     \fn void QCoapClient::error(QCoapReply *reply, QtCoap::Error error)
 
     This signal is emitted whenever an error occurs. The \a reply parameter
-    can be null if the error is not related to a specific QCoapReply.
+    can be \nullptr if the error is not related to a specific QCoapReply. The
+    \a error parameter contains the error code.
 
     \sa finished(), QCoapReply::error(), QCoapReply::finished()
 */
@@ -441,7 +443,7 @@ QCoapDiscoveryReply *QCoapClient::discover(QtCoap::MulticastGroup group,
 /*!
     Discovers the resources available at the given \a url and returns
     a new QCoapDiscoveryReply object which emits the
-    \l{QCoapReply::discovered()}{discovered()} signal whenever the response
+    \l QCoapDiscoveryReply::discovered() signal whenever the response
     arrives.
 
     Discovery path defaults to "/.well-known/core", but can be changed
@@ -466,8 +468,7 @@ QCoapDiscoveryReply *QCoapClient::discover(const QUrl &url, const QString &disco
 
 /*!
     Sends a request to observe the target \a request and returns
-    a new QCoapReply object which emits the
-    \l{QCoapReply::notified(const QByteArray&)}{notified(const QByteArray&)}
+    a new QCoapReply object which emits the \l QCoapReply::notified()
     signal whenever a new notification arrives.
 
     \sa cancelObserve(), get(), post(), put(), deleteResource(), discover()
@@ -490,8 +491,7 @@ QCoapReply *QCoapClient::observe(const QCoapRequest &request)
     \overload
 
     Sends a request to observe the target \a url and returns
-    a new QCoapReply object which emits the
-    \l{QCoapReply::notified(const QByteArray&)}{notified(const QByteArray&)}
+    a new QCoapReply object which emits the \l QCoapReply::notified()
     signal whenever a new notification arrives.
 
     \sa cancelObserve(), get(), post(), put(), deleteResource(), discover()
@@ -621,8 +621,9 @@ void QCoapClient::setSecurityConfiguration(const QCoapSecurityConfiguration &con
 }
 
 /*!
-    Sets the maximum block size used by the protocol when sending requests
-    and receiving replies. The block size must be a power of two.
+    Sets the maximum block size used by the protocol to \a blockSize
+    when sending requests and receiving replies. The block size must be
+    a power of two.
 
     \sa QCoapProtocol::setBlockSize()
 */
diff --git a/src/coap/qcoapconnection.cpp b/src/coap/qcoapconnection.cpp
index 921bd61..2e6e367 100644
--- a/src/coap/qcoapconnection.cpp
+++ b/src/coap/qcoapconnection.cpp
@@ -33,6 +33,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QCoapConnection
+    \inmodule QtCoap
 
     \brief The QCoapConnection class defines an interface for
     handling transfers of frames to a server.
@@ -42,6 +43,19 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \enum QCoapConnection::ConnectionState
+
+    This enum specifies the state of the underlying transport.
+
+    \value Unconnected      The underlying transport is not yet ready for data transmission.
+
+    \value Bound            The underlying transport is ready for data transmission. For example,
+                            if QUdpSocket is used for the transport, this corresponds to
+                            QAbstractSocket::BoundState.
+    \sa state(), bound()
+*/
+
+/*!
     \fn void QCoapConnection::error(QAbstractSocket::SocketError error)
 
     This signal is emitted when a connection error occurs. The \a error
@@ -52,7 +66,7 @@ QT_BEGIN_NAMESPACE
     \fn void QCoapConnection::readyRead(const QByteArray &data, const QHostAddress &sender)
 
     This signal is emitted when a network reply is available. The \a data
-    parameter supplies the received data, and the \sender parameter supplies
+    parameter supplies the received data, and the \a sender parameter supplies
     the sender address.
 */
 
@@ -97,7 +111,8 @@ QCoapConnectionPrivate::QCoapConnectionPrivate(QtCoap::SecurityMode security)
 {}
 
 /*!
-    Constructs a new QCoapConnection object and sets \a parent as the parent object.
+    Constructs a new CoAP connection for the given \a securityMode and
+    sets \a parent as its parent.
 */
 QCoapConnection::QCoapConnection(QtCoap::SecurityMode securityMode, QObject *parent)
     : QCoapConnection(*new QCoapConnectionPrivate(securityMode), parent)
@@ -107,7 +122,7 @@ QCoapConnection::QCoapConnection(QtCoap::SecurityMode securityMode, QObject *par
 /*!
     \internal
 
-    Constructs a new QCoapConnection as a child of \a parent, with \a dd
+    Constructs a new new CoAP connection as a child of \a parent, with \a dd
     as its \c d_ptr. This constructor must be used when internally subclassing
     the QCoapConnection class.
 */
diff --git a/src/coap/qcoapdiscoveryreply.cpp b/src/coap/qcoapdiscoveryreply.cpp
index acefe29..379277a 100644
--- a/src/coap/qcoapdiscoveryreply.cpp
+++ b/src/coap/qcoapdiscoveryreply.cpp
@@ -66,16 +66,21 @@ void QCoapDiscoveryReplyPrivate::_q_setContent(const QHostAddress &sender, const
 
 /*!
     \class QCoapDiscoveryReply
-    \brief A QCoapDiscoveryReply object is a QCoapReply that stores also a
-    list of QCoapResources.
+    \inmodule QtCoap
+
+    \brief The QCoapDiscoveryReply class holds the data of a CoAP reply
+    for a resource discovery request.
 
     \reentrant
 
-    This class is used for discovery requests, and emits the discovered()
+    This class is used for discovery requests. It emits the discovered()
     signal if and when resources are discovered. When using a multicast
     address for discovery, the discovered() signal will be emitted once
     for each response received.
 
+    \note A QCoapDiscoveryReply is a QCoapReply that stores also a list
+    of QCoapResources.
+
     \sa QCoapClient, QCoapRequest, QCoapReply, QCoapResource
 */
 
@@ -92,7 +97,8 @@ void QCoapDiscoveryReplyPrivate::_q_setContent(const QHostAddress &sender, const
 */
 
 /*!
-    Constructs a new QCoapDiscoveryReply and sets \a parent as parent object.
+    Constructs a new CoAP discovery reply from the \a request and sets \a parent
+    as its parent.
 */
 QCoapDiscoveryReply::QCoapDiscoveryReply(const QCoapRequest &request, QObject *parent) :
     QCoapReply(*new QCoapDiscoveryReplyPrivate(request), parent)
diff --git a/src/coap/qcoapmessage.cpp b/src/coap/qcoapmessage.cpp
index 390dc21..49e8030 100644
--- a/src/coap/qcoapmessage.cpp
+++ b/src/coap/qcoapmessage.cpp
@@ -50,6 +50,8 @@ QCoapMessagePrivate::~QCoapMessagePrivate()
 
 /*!
     \class QCoapMessage
+    \inmodule QtCoap
+
     \brief The QCoapMessage class holds information about a CoAP message that
     can be a request or a reply.
 
@@ -62,26 +64,32 @@ QCoapMessagePrivate::~QCoapMessagePrivate()
 */
 
 /*!
-    \enum QCoapMessage::QCoapMessageType
+    \enum QCoapMessage::MessageType
 
     Indicates the type of the message.
 
-    \value ConfirmableCoapMessage       A Confirmable message. The destination
+    \value Confirmable                  A Confirmable message. The destination
                                         endpoint needs to acknowledge the
                                         message.
-    \value NonConfirmableCoapMessage    A Non-Confirmable message. The
+    \value NonConfirmable               A Non-Confirmable message. The
                                         destination endpoint does not need to
                                         acknowledge the message.
-    \value AcknowledgmentCoapMessage    An Acknowledgment message. A message
+    \value Acknowledgment               An Acknowledgment message. A message
                                         sent or received in reply to a
                                         Confirmable message.
-    \value ResetCoapMessage             A Reset message. A message sent
-                                        sometimes in case of errors or to stop
-                                        transmissions. (For example, it is used
+    \value Reset                        A Reset message. This message type is used
+                                        in case of errors or to stop the ongoing
+                                        transmission. (For example, it is used
                                         to cancel an observation).
 */
 
 /*!
+    \fn void QCoapMessage::swap(QCoapMessage &other)
+
+    Swaps this message with \a other. This operation is very fast and never fails.
+*/
+
+/*!
     Constructs a new QCoapMessage.
 */
 QCoapMessage::QCoapMessage() :
@@ -276,7 +284,8 @@ QVector<QCoapOption>::const_iterator QCoapMessage::findOption(QCoapOption::Optio
 }
 
 /*!
-    Returns \c true if option is present at least once.
+    Returns \c true if the message contains at last one option
+    with \a name.
 */
 bool QCoapMessage::hasOption(QCoapOption::OptionName name) const
 {
@@ -318,7 +327,7 @@ int QCoapMessage::optionCount() const
 }
 
 /*!
-    Sets the CoAP version.
+    Sets the CoAP version to \a version.
 
     \sa version()
 */
@@ -329,7 +338,7 @@ void QCoapMessage::setVersion(quint8 version)
 }
 
 /*!
-    Sets the message type.
+    Sets the message type to \a type.
 
     \sa type()
 */
@@ -340,7 +349,7 @@ void QCoapMessage::setType(const MessageType &type)
 }
 
 /*!
-    Sets the token.
+    Sets the message token to \a token.
 
     \sa token()
 */
@@ -351,7 +360,7 @@ void QCoapMessage::setToken(const QByteArray &token)
 }
 
 /*!
-    Sets the message id.
+    Sets the message ID to \a id.
 
     \sa messageId()
 */
@@ -362,7 +371,7 @@ void QCoapMessage::setMessageId(quint16 id)
 }
 
 /*!
-    Sets the payload.
+    Sets the message payload to \a payload.
 
     \sa payload()
 */
@@ -378,7 +387,7 @@ void QCoapMessage::swap(QCoapMessage &other) Q_DECL_NOTHROW
 }
 
 /*!
-    Move assignment operator.
+    Move-assignment operator.
  */
 QCoapMessage &QCoapMessage::operator=(QCoapMessage &&other) Q_DECL_NOTHROW
 {
@@ -387,7 +396,8 @@ QCoapMessage &QCoapMessage::operator=(QCoapMessage &&other) Q_DECL_NOTHROW
 }
 
 /*!
-    Assignment operator.
+    Copies the contents of \a other into this message.
+    Returns a reference to this QCoapMessage.
  */
 QCoapMessage &QCoapMessage::operator=(const QCoapMessage &other)
 {
diff --git a/src/coap/qcoapoption.cpp b/src/coap/qcoapoption.cpp
index b3058f5..834d282 100644
--- a/src/coap/qcoapoption.cpp
+++ b/src/coap/qcoapoption.cpp
@@ -35,11 +35,19 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QCoapOption
+    \inmodule QtCoap
+
     \brief The QCoapOption class holds data about CoAP options.
 
     \reentrant
 
-    An option contains a name, related to an option id, and a value.
+    CoAP defines a number of options that can be included in a message.
+    Both requests and responses may include a list of one or more
+    options.  For example, the URI in a request is transported in several
+    options, and metadata that would be carried in an HTTP header in HTTP
+    is supplied as options as well.
+
+    An option contains a name, related to an option ID, and a value.
     The name is one of the values from the OptionName enumeration.
 */
 
@@ -52,29 +60,30 @@ QT_BEGIN_NAMESPACE
     \l{https://tools.ietf.org/html/rfc7252#section-5.10}{RFC 7252} and
     \l{https://tools.ietf.org/html/rfc7959#section-2.1}{RFC 7959} for more details.
 
-    \value IfMatchCoapOption        If-Match
-    \value UriHostCoapOption        Uri-Host
-    \value EtagCoapOption           Etag
-    \value IfNoneMatchCoapOption    If-None-Match
-    \value ObserveCoapOption        Observe
-    \value UriPortCoapOption        Uri-Port
-    \value LocationPathCoapOption   Location-path
-    \value UriPathCoapOption        Uri-Path
-    \value ContentFormatCoapOption  Content-Format
-    \value MaxAgeCoapOption         Max-Age
-    \value UriQueryCoapOption       Uri-Query
-    \value AcceptCoapOption         Accept
-    \value LocationQueryCoapOption  Location-Query
-    \value Block2CoapOption         Block2
-    \value Block1CoapOption         Block1
-    \value Size2CoapOption          Size2
-    \value ProxyUriCoapOption       Proxy-Uri
-    \value ProxySchemeCoapOption    Proxy-Scheme
-    \value Size1CoapOption          Size1
+    \value Invalid                  An invalid option.
+    \value IfMatch                  If-Match option.
+    \value UriHost                  Uri-Host option.
+    \value Etag                     Etag option.
+    \value IfNoneMatch              If-None-Match option.
+    \value Observe                  Observe option.
+    \value UriPort                  Uri-Port option.
+    \value LocationPath             Location-path option.
+    \value UriPath                  Uri-Path option.
+    \value ContentFormat            Content-Format option.
+    \value MaxAge                   Max-Age option.
+    \value UriQuery                 Uri-Query option.
+    \value Accept                   Accept option.
+    \value LocationQuery            Location-Query option.
+    \value Block2                   Block2 option.
+    \value Block1                   Block1 option.
+    \value Size2                    Size2 option.
+    \value ProxyUri                 Proxy-Uri option.
+    \value ProxyScheme              Proxy-Scheme option.
+    \value Size1                    Size1 option.
 */
 
 /*!
-    Constructs a QCoapOption object with the given \a name
+    Constructs a new CoAP option with the given \a name
     and QByteArray \a value.
     If no parameters are passed, constructs an Invalid object.
 
@@ -89,7 +98,7 @@ QCoapOption::QCoapOption(OptionName name, const QByteArray &value) :
 }
 
 /*!
-    Constructs a QCoapOption object with the given \a name
+    Constructs a new CoAP option with the given \a name
     and the QStringView \a value.
 
     \sa isValid()
@@ -103,7 +112,7 @@ QCoapOption::QCoapOption(OptionName name, QStringView value) :
 }
 
 /*!
-    Constructs a QCoapOption object with the given \a name
+    Constructs a new CoAP option with the given \a name
     and the string \a value.
 
     \sa isValid()
@@ -117,7 +126,7 @@ QCoapOption::QCoapOption(OptionName name, const char *value) :
 }
 
 /*!
-    Constructs a QCoapOption object with the given \a name
+    Constructs a new CoAP option with the given \a name
     and the unsigned integer \a value.
 
     \sa isValid()
@@ -131,7 +140,8 @@ QCoapOption::QCoapOption(OptionName name, quint32 value) :
 }
 
 /*!
-    Constructs a QCoapOption object by copy from an \a other QCoapOption.
+    Constructs a new CoAP option as a copy of \a other, making the two
+    options identical.
 
     \sa isValid()
  */
@@ -141,7 +151,8 @@ QCoapOption::QCoapOption(const QCoapOption &other) :
 }
 
 /*!
-    QCoapOption move constructor.
+    Move-constructs a QCoapOption, making it point to the same object
+    as \a other was pointing to.
  */
 QCoapOption::QCoapOption(QCoapOption &&other) :
     d_ptr(other.d_ptr)
@@ -150,7 +161,7 @@ QCoapOption::QCoapOption(QCoapOption &&other) :
 }
 
 /*!
-    Destroys QCoapOption object.
+    Destroys the QCoapOption object.
  */
 QCoapOption::~QCoapOption()
 {
@@ -158,7 +169,8 @@ QCoapOption::~QCoapOption()
 }
 
 /*!
-    Assignment operator.
+    Copies \a other into this option, making the two options identical.
+    Returns a reference to this QCoapOption.
  */
 QCoapOption &QCoapOption::operator=(const QCoapOption &other)
 {
@@ -168,7 +180,7 @@ QCoapOption &QCoapOption::operator=(const QCoapOption &other)
 }
 
 /*!
-    Move assignment operator.
+    Move-assignment operator.
  */
 QCoapOption &QCoapOption::operator=(QCoapOption &&other) Q_DECL_NOTHROW
 {
@@ -177,7 +189,7 @@ QCoapOption &QCoapOption::operator=(QCoapOption &&other) Q_DECL_NOTHROW
 }
 
 /*!
-    Swap object with another.
+    Swaps this option with \a other. This operation is very fast and never fails.
  */
 void QCoapOption::swap(QCoapOption &other) Q_DECL_NOTHROW
 {
diff --git a/src/coap/qcoapprotocol.cpp b/src/coap/qcoapprotocol.cpp
index d78baf1..fc5e4eb 100644
--- a/src/coap/qcoapprotocol.cpp
+++ b/src/coap/qcoapprotocol.cpp
@@ -41,6 +41,8 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QCoapProtocol
+    \inmodule QtCoap
+
     \brief The QCoapProtocol class handles the logical part of the CoAP
     protocol.
 
@@ -55,6 +57,38 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn void QCoapProtocol::finished(QCoapReply *reply)
+
+    This signal is emitted along with the \l QCoapReply::finished() signal
+    whenever a CoAP reply is received, after either a success or an error.
+    The \a reply parameter will contain a pointer to the reply that has just
+    been received.
+
+    \sa error(), QCoapReply::finished(), QCoapReply::error()
+*/
+
+/*!
+    \fn void QCoapProtocol::responseToMulticastReceived(QCoapReply *reply,
+                                                        const QCoapMessage& message)
+
+    This signal is emitted when a unicast response to a multicast request
+    arrives. The \a reply parameter contains a pointer to the reply that has just
+    been received, and \a message contains the payload and the message details.
+
+    \sa error(), QCoapReply::finished(), QCoapReply::error()
+*/
+
+/*!
+    \fn void QCoapProtocol::error(QCoapReply *reply, QtCoap::Error error)
+
+    This signal is emitted whenever an error occurs. The \a reply parameter
+    can be \nullptr if the error is not related to a specific QCoapReply. The
+    \a error parameter contains the error code.
+
+    \sa finished(), QCoapReply::error(), QCoapReply::finished()
+*/
+
+/*!
     Constructs a new QCoapProtocol and sets \a parent as the parent object.
 */
 QCoapProtocol::QCoapProtocol(QObject *parent) :
@@ -706,8 +740,9 @@ void QCoapProtocolPrivate::onConnectionError(QAbstractSocket::SocketError socket
 }
 
 /*!
-    Decodes the \a data to a list of QCoapResource objects.
-    The \a data byte array is a frame returned by a discovery request.
+    Decodes the \a data received from the \a sender to a list of QCoapResource
+    objects. The \a data byte array contains the frame returned by the
+    discovery request.
 */
 QVector<QCoapResource> QCoapProtocol::resourcesFromCoreLinkList(const QHostAddress &sender,
                                                                 const QByteArray &data)
diff --git a/src/coap/qcoapqudpconnection.cpp b/src/coap/qcoapqudpconnection.cpp
index a647fbd..ecba9b5 100644
--- a/src/coap/qcoapqudpconnection.cpp
+++ b/src/coap/qcoapqudpconnection.cpp
@@ -43,7 +43,10 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QCoapQUdpConnection
-    \brief A QCoapQUdpConnection transfers frames to and from a server.
+    \inmodule QtCoap
+
+    \brief The QCoapQUdpConnection class handles the transfer of frames to
+    and from a server.
 
     \reentrant
 
diff --git a/src/coap/qcoapreply.cpp b/src/coap/qcoapreply.cpp
index a236c52..f3db863 100644
--- a/src/coap/qcoapreply.cpp
+++ b/src/coap/qcoapreply.cpp
@@ -35,8 +35,8 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \class QCoapReplyPrivate
-    \brief Class's constructor
+    \internal
+    Constructor.
 */
 QCoapReplyPrivate::QCoapReplyPrivate(const QCoapRequest &req) :
     request(req)
@@ -163,6 +163,8 @@ void QCoapReplyPrivate::_q_setError(QtCoap::ResponseCode code)
 
 /*!
     \class QCoapReply
+    \inmodule QtCoap
+
     \brief The QCoapReply class holds the data of a CoAP reply.
 
     \reentrant
@@ -170,12 +172,11 @@ void QCoapReplyPrivate::_q_setError(QtCoap::ResponseCode code)
     The QCoapReply contains data related to a request sent with the
     QCoapClient.
 
-    The \l{QCoapReply::finished(QCoapReply*)}{finished(QCoapReply*)} signal is
-    emitted when the response is fully received or when the request fails.
+    The finished() signal is emitted when the response is fully
+    received or when the request fails.
 
-    For Observe requests specifically, the
-    \l{QCoapReply::notified(QCoapReply*, const QByteArray&)}{notified(QCoapReply*, const QByteArray&)}
-    signal is emitted whenever a notification is received.
+    For \e Observe requests specifically, the notified() signal is emitted
+    whenever a notification is received.
 
     \sa QCoapClient, QCoapRequest, QCoapDiscoveryReply
 */
@@ -237,7 +238,8 @@ void QCoapReplyPrivate::_q_setError(QtCoap::ResponseCode code)
 */
 
 /*!
-    Constructs a QCoapReply object and sets \a parent as the parent object.
+    Constructs a new CoAP reply for the \a request and sets \a parent as
+    its parent.
 */
 QCoapReply::QCoapReply(const QCoapRequest &request, QObject *parent) :
     QCoapReply(*new QCoapReplyPrivate(request), parent)
@@ -246,7 +248,7 @@ QCoapReply::QCoapReply(const QCoapRequest &request, QObject *parent) :
 
 /*!
     \internal
-    Constructs a new QCoapReply with \a dd as the d_ptr.
+    Constructs a new CoAP reply with \a dd as the d_ptr.
     This constructor must be used when subclassing internally
     the QCoapReply class.
 */
@@ -257,7 +259,7 @@ QCoapReply::QCoapReply(QCoapReplyPrivate &dd, QObject *parent) :
 }
 
 /*!
-    Destroys the QCoapReply object and aborts the request if its response has
+    Destroys the QCoapReply and aborts the request if its response has
     not yet been received.
 */
 QCoapReply::~QCoapReply()
@@ -328,8 +330,6 @@ QCoapMessage QCoapReply::message() const
 
 /*!
     Returns the associated request.
-
-    \sa setRequest()
 */
 QCoapRequest QCoapReply::request() const
 {
diff --git a/src/coap/qcoaprequest.cpp b/src/coap/qcoaprequest.cpp
index b75be82..e23c806 100644
--- a/src/coap/qcoaprequest.cpp
+++ b/src/coap/qcoaprequest.cpp
@@ -94,6 +94,8 @@ void QCoapRequestPrivate::setUrl(const QUrl &url)
 
 /*!
     \class QCoapRequest
+    \inmodule QtCoap
+
     \brief The QCoapRequest class holds a CoAP request. This request
     can be sent with QCoapClient.
 
diff --git a/src/coap/qcoapresource.cpp b/src/coap/qcoapresource.cpp
index bdb5fa6..c24950e 100644
--- a/src/coap/qcoapresource.cpp
+++ b/src/coap/qcoapresource.cpp
@@ -34,6 +34,8 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QCoapResource
+    \inmodule QtCoap
+
     \brief The QCoapResource class holds information about a discovered
     resource.
 
@@ -54,8 +56,9 @@ QCoapResource::QCoapResource() :
 }
 
 /*!
-    Copy constructs a new QCoapResource.
- */
+    Constructs a new CoAP resource as a copy of \a other, making the two
+    resources identical.
+*/
 QCoapResource::QCoapResource(const QCoapResource &other) :
     d(other.d)
 {
@@ -69,16 +72,17 @@ QCoapResource::~QCoapResource()
 }
 
 /*!
-    Assignment operator.
- */
-QCoapResource &QCoapResource::operator =(const QCoapResource &other)
+    Copies \a other into this resource, making the two resources identical.
+    Returns a reference to this QCoapResource.
+*/
+QCoapResource &QCoapResource::operator=(const QCoapResource &other)
 {
     d = other.d;
     return *this;
 }
 
 /*!
-    Swap function for Q_DECLARE_SHARED
+    Swaps this resource with \a other. This operation is very fast and never fails.
  */
 void QCoapResource::swap(QCoapResource &other) Q_DECL_NOTHROW
 {
@@ -180,7 +184,7 @@ uint QCoapResource::contentFormat() const
 }
 
 /*!
-    Sets the host of the resource.
+    Sets the host of the resource to \a host.
 
     \sa host()
  */
@@ -190,7 +194,7 @@ void QCoapResource::setHost(const QHostAddress &host)
 }
 
 /*!
-    Sets the path of the resource.
+    Sets the path of the resource to \a path.
 
     \sa path()
  */
@@ -200,7 +204,7 @@ void QCoapResource::setPath(const QString &path)
 }
 
 /*!
-    Sets the title of the resource.
+    Sets the title of the resource to \a title.
 
     \sa title()
  */
@@ -210,8 +214,8 @@ void QCoapResource::setTitle(const QString &title)
 }
 
 /*!
-    Set it to \c true to indicate that the resource
-    is observable.
+    Makes the resource observable if the \a observable
+    parameter is \c true.
 
     \sa observable()
  */
@@ -221,7 +225,7 @@ void QCoapResource::setObservable(bool observable)
 }
 
 /*!
-    Sets the resource type.
+    Sets the resource type to \a resourceType.
 
     \sa resourceType()
  */
@@ -231,7 +235,7 @@ void QCoapResource::setResourceType(const QString &resourceType)
 }
 
 /*!
-    Sets the interface of the resource.
+    Sets the interface of the resource to \a interface.
 
     \sa interface()
  */
@@ -241,7 +245,7 @@ void QCoapResource::setInterface(const QString &interface)
 }
 
 /*!
-    Sets the maximum size of the resource.
+    Sets the maximum size of the resource to \a maximumSize.
 
     \sa maximumSize()
  */
@@ -251,7 +255,7 @@ void QCoapResource::setMaximumSize(int maximumSize)
 }
 
 /*!
-    Sets the content format of the resource.
+    Sets the content format of the resource to \a contentFormat.
 
     \sa contentFormat()
  */
diff --git a/src/coap/qcoapsecurityconfiguration.cpp b/src/coap/qcoapsecurityconfiguration.cpp
index 785f891..8c26dd2 100644
--- a/src/coap/qcoapsecurityconfiguration.cpp
+++ b/src/coap/qcoapsecurityconfiguration.cpp
@@ -59,9 +59,20 @@ public:
 
 /*!
     \class QCoapPrivateKey
+    \inmodule QtCoap
 
-    The QCoapPrivateKey class provides an interface for private keys used
-    for CoAP security.
+    \brief The QCoapPrivateKey class provides an interface for managing
+    CoAP security keys.
+
+    A QCoapPrivateKey packages a private key used in negotiating CoAP connections
+    securely. It holds the information required for authentication using
+    \c pre-shared keys and X.509 certificates.
+*/
+
+/*!
+    \fn void QCoapPrivateKey::swap(QCoapPrivateKey &other)
+
+    Swaps this private key with \a other. This operation is very fast and never fails.
 */
 
 /*!
@@ -109,7 +120,8 @@ QCoapPrivateKey::QCoapPrivateKey(const QCoapPrivateKey &other)
 }
 
 /*!
-    Move-constructs a QCoapPrivateKey.
+    Move-constructs a QCoapPrivateKey, making it point to the same
+    object as \a other was pointing to.
 */
 QCoapPrivateKey::QCoapPrivateKey(QCoapPrivateKey &&other) Q_DECL_NOTHROW
     : d(other.d)
@@ -186,11 +198,21 @@ QByteArray QCoapPrivateKey::passPhrase() const
 
 /*!
     \class QCoapSecurityConfiguration
+    \inmodule QtCoap
+
     \brief The QCoapSecurityConfiguration class holds configuration
     options during the authentication process.
 
     It holds information such as client identity, pre shared key, information
-    about certificates and so on.
+    about certificates, and so on.
+*/
+
+
+/*!
+    \fn void QCoapSecurityConfiguration::swap(QCoapSecurityConfiguration &other)
+
+    Swaps this security configuration with \a other. This operation is very fast
+    and never fails.
 */
 
 /*!
@@ -211,7 +233,7 @@ QCoapSecurityConfiguration::QCoapSecurityConfiguration(const QCoapSecurityConfig
 
 /*!
     Move-constructs a QCoapSecurityConfiguration, making it point to the same
-    object that \a other was pointing to.
+    object as \a other was pointing to.
 */
 QCoapSecurityConfiguration::QCoapSecurityConfiguration(
         QCoapSecurityConfiguration &&other) Q_DECL_NOTHROW
@@ -340,7 +362,7 @@ void QCoapSecurityConfiguration::setLocalCertificateChain(const QVector<QSslCert
 /*!
     Returns the certificate chain to be presented to the peer during the handshake.
 
-    \sa setLocalCertificate()
+    \sa setLocalCertificateChain()
 */
 QVector<QSslCertificate> QCoapSecurityConfiguration::localCertificateChain() const
 {
@@ -350,7 +372,7 @@ QVector<QSslCertificate> QCoapSecurityConfiguration::localCertificateChain() con
 /*!
     Sets the connection's private key to \a key.
 
-    \sa privateKey(), setLocalCertificate()
+    \sa privateKey(), setLocalCertificateChain()
 */
 void QCoapSecurityConfiguration::setPrivateKey(const QCoapPrivateKey &key)
 {
@@ -360,7 +382,7 @@ void QCoapSecurityConfiguration::setPrivateKey(const QCoapPrivateKey &key)
 /*!
     Returns the private key assigned to the connection.
 
-    \sa setPrivateKey(), localCertificate()
+    \sa setPrivateKey(), localCertificateChain()
 */
 QCoapPrivateKey QCoapSecurityConfiguration::privateKey() const
 {