Document the simplecoapclient example

Change-Id: I066acf1d2765f4c48392371e50f86f694c1af7bc
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

3 files changed, 139 insertions, 5 deletions

diff --git a/examples/coap/doc/images/simplecoapclient.png b/examples/coap/doc/images/simplecoapclient.png
new file mode 100644
index 0000000..b77dc96
--- /dev/null
+++ b/examples/coap/doc/images/simplecoapclient.png
diff --git a/examples/coap/doc/simplecoapclient.qdoc b/examples/coap/doc/simplecoapclient.qdoc
index 6ca6459..961d473 100644
--- a/examples/coap/doc/simplecoapclient.qdoc
+++ b/examples/coap/doc/simplecoapclient.qdoc
@@ -30,4 +30,138 @@
     \title Simple CoAP Client Example
     \ingroup qtcoap-examples
     \brief Creating an application that communicates with a CoAP server.
+
+    \image simplecoapclient.png
+
+    \e {Simple CoAP Client} demonstrates how to create a minimalistic CoAP client
+    application to send and receive CoAP messages.
+
+    \section1 Setting Up a CoAP Server
+
+    To use the application, you need to specify a CoAP server. You have the following
+    options:
+
+    \list
+        \li Use the CoAP test server located at \c {coap://coap.me}.
+        \li Create a CoAP server using \l {https://github.com/obgm/libcoap} {libcoap},
+        \l {https://github.com/keith-cullen/FreeCoAP} {FreeCoAP} or any other CoAP
+        server implementation.
+        \li Use the \l {https://github.com/eclipse/californium/} {Californium} plugtest
+        server, which supports most of the CoAP features. You can build it manually or
+        use a ready Docker image, which builds and starts the plugtest server. The steps
+        for using the docker-based server are described below.
+
+    \endlist
+
+    \section2 Using the Docker-based Test Server
+
+    The following command pulls the docker container for the CoAP server from the Docker
+    Hub and starts it:
+
+    \badcode
+    docker run --name coap-test-server -d --rm -p 5683:5683/udp -p 5684:5684/udp sokurazy/coap-secure-test-server:californium.1.1.0
+    \endcode
+
+    To find out the IP address of the docker container, first retrieve the container ID
+    by running \c {docker ps}, which will output something like:
+
+    \badcode
+    $ docker ps
+    CONTAINER ID        IMAGE
+    5e46502df88f        sonakur/coap-secure-test-server:californium.1.1.0
+    \endcode
+
+    Then you can obtain the IP address with the following command:
+
+    \badcode
+    docker inspect <container_id> | grep IPAddress
+    \endcode
+
+    For example:
+
+    \badcode
+    $ docker inspect 5e46502df88f | grep IPAddress
+    ...
+    "IPAddress": "172.17.0.2",
+    ...
+    \endcode
+
+    The CoAP test server will be reachable by the retrieved IP address on ports
+    \e 5683 (non-secure) and \e 5684 (secure).
+
+    \section1 Creating a Client
+
+    The first step is to create a CoAP client using the QCoapClient class. Then
+    we need to connect its signals, to get notified when a CoAP reply is received
+    or a request has failed:
+
+    \quotefromfile simplecoapclient/mainwindow.cpp
+    \skipto MainWindow::MainWindow
+    \printuntil onError
+    \dots
+
+    \section1 Sending Requests
+    We use the QCoapRequest class to create CoAP requests. This class provides methods
+    for constructing CoAP frames.
+
+    \skipto on_runButton_clicked
+    \printuntil addOption
+    \dots
+
+    In this example, we set the URL, as well as the message type and add options
+    to the request. It is also possible to set the payload, message ID, token,
+    and so on, but we are using the default values here. Note that by default,
+    the message ID and token are generated randomly.
+
+    Based on the selected request method, we send a \c GET, \c PUT, \c POST or
+    \c DELETE request to the server:
+
+    \skipto switch
+    \dots
+    \printuntil }
+    \dots
+
+    For \c PUT and \c POST requests we also add \c m_currentData as a payload for
+    the request.
+
+    For browsing the contents of the server and discovering the resources available on
+    it, a \e discovery request is used:
+
+    \skipto on_discoverButton_clicked
+    \printuntil {
+    \dots
+    \skipto discoverReply
+    \printuntil onDiscovered
+    \dots
+
+    \note Instead of QCoapReply class, we use the QCoapDiscoveryReply to keep
+    the reply for a discovery request. It has the QCoapDiscoveryReply::discovered
+    signal, which returns the list of QCoapResources that has been discovered.
+
+    If there are \e observable resources on the server (meaning that they have the
+    resource type \c obs), we can subscribe to updates on that resource by running
+    an \e observe request:
+
+    \skipto on_observeButton_clicked
+    \printuntil {
+    \dots
+    \skipto observeReply
+    \printline observeReply
+    \dots
+    \skipto onNotified
+    \printline onNotified
+    \dots
+
+    The client can unsubscribe from the resource observation by handling the
+    \c clicked() signal of the \c cancelObserveButton:
+
+    \skipto clicked
+    \dots
+    \printuntil })
+
+    The responses coming from the server are displayed in the UI:
+
+    \quotefromfile simplecoapclient/mainwindow.cpp
+    \skipto MainWindow::addMessage
+    \printto on_runButton_clicked
 */
diff --git a/examples/coap/simplecoapclient/mainwindow.cpp b/examples/coap/simplecoapclient/mainwindow.cpp
index c14f3ce..193e3e2 100644
--- a/examples/coap/simplecoapclient/mainwindow.cpp
+++ b/examples/coap/simplecoapclient/mainwindow.cpp
@@ -63,9 +63,12 @@
 
 MainWindow::MainWindow(QWidget *parent) :
     QMainWindow(parent),
-    ui(new Ui::MainWindow),
-    m_client(new QCoapClient(QtCoap::NoSec, this))
+    ui(new Ui::MainWindow)
 {
+    m_client = new QCoapClient(QtCoap::NoSec, this);
+    connect(m_client, &QCoapClient::finished, this, &MainWindow::onFinished);
+    connect(m_client, &QCoapClient::error, this, &MainWindow::onError);
+
     ui->setupUi(this);
 
     ui->methodComboBox->addItem("Get", QtCoap::Method::Get);
@@ -75,9 +78,6 @@ MainWindow::MainWindow(QWidget *parent) :
 
     fillHostSelector();
     ui->hostComboBox->setFocus();
-
-    connect(m_client, &QCoapClient::finished, this, &MainWindow::onFinished);
-    connect(m_client, &QCoapClient::error, this, &MainWindow::onError);
 }
 
 MainWindow::~MainWindow()