add some code docs for QXmppIceConnection

2 files changed, 35 insertions, 0 deletions

diff --git a/src/base/QXmppStun.cpp b/src/base/QXmppStun.cpp
index 221fbfe7..18a3342d 100644
--- a/src/base/QXmppStun.cpp
+++ b/src/base/QXmppStun.cpp
@@ -2623,6 +2623,9 @@ bool QXmppIceConnection::isConnected() const
 }
 
 /// Sets whether the local party has the ICE controlling role.
+///
+/// \a note This must be called only once, immediately after creating
+/// the connection.
 
 void QXmppIceConnection::setIceControlling(bool controlling)
 {
@@ -2675,6 +2678,8 @@ void QXmppIceConnection::setRemotePassword(const QString &password)
 /// Sets the STUN server to use to determine server-reflexive addresses
 /// and ports.
 ///
+/// \note This may only be called prior to calling bind().
+///
 /// \param host The address of the STUN server.
 /// \param port The port of the STUN server.
 
@@ -2686,6 +2691,8 @@ void QXmppIceConnection::setStunServer(const QHostAddress &host, quint16 port)
 
 /// Sets the TURN server to use to relay packets in double-NAT configurations.
 ///
+/// \note This may only be called prior to calling bind().
+///
 /// \param host The address of the TURN server.
 /// \param port The port of the TURN server.
 
@@ -2699,6 +2706,8 @@ void QXmppIceConnection::setTurnServer(const QHostAddress &host, quint16 port)
 
 /// Sets the \a user used for authentication with the TURN server.
 ///
+/// \note This may only be called prior to calling bind().
+///
 /// \param user
 
 void QXmppIceConnection::setTurnUser(const QString &user)
@@ -2710,6 +2719,8 @@ void QXmppIceConnection::setTurnUser(const QString &user)
 
 /// Sets the \a password used for authentication with the TURN server.
 ///
+/// \note This may only be called prior to calling bind().
+///
 /// \param password
 
 void QXmppIceConnection::setTurnPassword(const QString &password)
diff --git a/src/base/QXmppStun.h b/src/base/QXmppStun.h
index 41659b7f..cc8b01c1 100644
--- a/src/base/QXmppStun.h
+++ b/src/base/QXmppStun.h
@@ -209,6 +209,30 @@ private:
 /// \brief The QXmppIceConnection class represents a set of UDP sockets
 /// capable of performing Interactive Connectivity Establishment (RFC 5245).
 ///
+/// A typical example is:
+///
+/// \code
+/// QXmppIceConnection *connection = new QXmppIceConnection();
+/// connection->setIceControlling(true);
+/// connection->addComponent(1);
+///
+/// // if needed, set STUN / TURN configuration
+/// // connection->setStunServer(..);
+/// // connection->setTurnServer(..);
+///
+/// // start listening
+/// connection->bind(QXmppIceComponent::discoverAddresses());
+///
+/// // receive remote information: user, password, candidates
+/// // ...
+///
+/// // set remote information and start connecting
+/// connection->setRemoteUser("foo");
+/// connection->setRemoteUser("bar");
+/// connection->addRemoteCandidate(..);
+/// connection->connectToHost();
+///
+/// \endcode
 
 class QXMPP_EXPORT QXmppIceConnection : public QXmppLoggable
 {