Expand documentation of examples

Add to the documentation to include what the examples do and how they
do it, to make it easier for users to decide if an example is worth
looking into, instead of how it was where they had to look at the code
in the examples to decide if they are relevant for their purposes.
Also added pictures to the examples.

Task-number: QTBUG-110894
Pick-to: 6.5
Change-Id: I2751939e9f9716cd970e5fa938dabf042f369329
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

14 files changed, 124 insertions, 34 deletions

diff --git a/examples/websockets/doc/echoclient.qdoc b/examples/websockets/doc/echoclient.qdoc
index cf2ef82..f4b3ad3 100644
--- a/examples/websockets/doc/echoclient.qdoc
+++ b/examples/websockets/doc/echoclient.qdoc
@@ -3,12 +3,24 @@
 
 /*!
     \example echoclient
-    \title Echo Client Example
+    \title WebSocket Echo Client
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Describes how to use the WebSocket API for creating a simple echo client.
+    \brief Show how to write a simple WebSocket client application.
 
-    The Echo Client Example shows how to use the WebSocket API to create a simple
-    echo client.
+    The Echo Client shows how to use the \l {Qt WebSockets}{WebSocket}
+    API to send a message to a server and process whatever response the
+    server returns - in this case, simply reporting the response.
 
-    \sa {Echo Server Example}
+    The client opens a WebSocket connection to a server listening on local
+    port 1234. When the connection attempt is successful, the client will
+    send a message to the server and print out whatever response the server
+    sends. The client then closes the connection.
+
+    \image echoclient-console-example.webp WebSocket Echo Console Client
+
+    For the sake of illustration, we use the \l {WebSocket Echo Server}, whose
+    reply is simply the message that was sent.
+
+    \sa {WebSocket Echo Server}
 */
diff --git a/examples/websockets/doc/echoserver.qdoc b/examples/websockets/doc/echoserver.qdoc
index f314ac0..0728372 100644
--- a/examples/websockets/doc/echoserver.qdoc
+++ b/examples/websockets/doc/echoserver.qdoc
@@ -3,20 +3,23 @@
 
 /*!
     \example echoserver
-    \title Echo Server Example
+    \title WebSocket Echo Server
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Shows how to create a simple server application that
-    sends back the messages it receives.
+    \brief Show how to write a simple WebSocket server application.
 
-    The Echo Server Example shows how to create a simple server application that
-    sends back the messages it receives, using the \l {Qt WebSockets}{WebSocket} API.
+    This Echo Server shows how to create a simple server application that sends
+    back a reply in response to a message it receives, using the
+    \l {Qt WebSockets}{WebSocket} API. For the sake of illustration, the reply
+    is simply a copy of the message.
 
     If your web browser supports \l {Qt WebSockets}{WebSocket}, you can also use it
     to open the \c {echoserver/echoclient.html}{echoclient.html} file, and operate
-    like the following screenshot.
+    as shown in the following screenshot:
 
-    \image echoclient-html-example.png Screenshot of the HTML version of Echo
-    Client example
+    \image echoclient-html-example.png WebSocket Echo HTML Client
 
-    \sa {Echo Client Example}
+    Otherwise use the \l {WebSocket Echo Client} to connect to the server.
+
+    \sa {WebSocket Echo Client}
 */
diff --git a/examples/websockets/doc/examples.qdoc b/examples/websockets/doc/examples.qdoc
index 3599304..d22d8e5 100644
--- a/examples/websockets/doc/examples.qdoc
+++ b/examples/websockets/doc/examples.qdoc
@@ -5,6 +5,7 @@
 /*!
     \group qtwebsockets-examples
     \title Qt WebSockets Examples
+    \meta category {Networking}
     \brief List of Qt WebSocket examples
 
     The examples below can be used as a guide to using the \l{Qt WebSockets} API.
diff --git a/examples/websockets/doc/images/echoclient-console-example.webp b/examples/websockets/doc/images/echoclient-console-example.webp
new file mode 100644
index 0000000..1b43a44
--- /dev/null
+++ b/examples/websockets/doc/images/echoclient-console-example.webp
diff --git a/examples/websockets/doc/images/qmlwebsocketclient-example.webp b/examples/websockets/doc/images/qmlwebsocketclient-example.webp
new file mode 100644
index 0000000..24d5044
--- /dev/null
+++ b/examples/websockets/doc/images/qmlwebsocketclient-example.webp
diff --git a/examples/websockets/doc/images/qmlwebsocketserver-example.webp b/examples/websockets/doc/images/qmlwebsocketserver-example.webp
new file mode 100644
index 0000000..6a13216
--- /dev/null
+++ b/examples/websockets/doc/images/qmlwebsocketserver-example.webp
diff --git a/examples/websockets/doc/images/simplechat-html-example.webp b/examples/websockets/doc/images/simplechat-html-example.webp
new file mode 100644
index 0000000..e9808bb
--- /dev/null
+++ b/examples/websockets/doc/images/simplechat-html-example.webp
diff --git a/examples/websockets/doc/images/sslechoclient-console-example.webp b/examples/websockets/doc/images/sslechoclient-console-example.webp
new file mode 100644
index 0000000..561df52
--- /dev/null
+++ b/examples/websockets/doc/images/sslechoclient-console-example.webp
diff --git a/examples/websockets/doc/images/sslechoclient-html-example.webp b/examples/websockets/doc/images/sslechoclient-html-example.webp
new file mode 100644
index 0000000..b34060a
--- /dev/null
+++ b/examples/websockets/doc/images/sslechoclient-html-example.webp
diff --git a/examples/websockets/doc/qmlwebsocketclient.qdoc b/examples/websockets/doc/qmlwebsocketclient.qdoc
index d7f8ebd..e5770f2 100644
--- a/examples/websockets/doc/qmlwebsocketclient.qdoc
+++ b/examples/websockets/doc/qmlwebsocketclient.qdoc
@@ -3,7 +3,29 @@
 
 /*!
     \example qmlwebsocketclient
-    \title QML WebSocket Client Example
+    \title QML WebSocket Client
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Explains how to program a QML WebSocket client example.
+    \brief Explains how to write a QML WebSocket client example.
+
+    The QML WebSocket Client example creates a secure and an
+    insecure \l {Qt WebSockets}{WebSocket} connection to an echo
+    server, using the QML API, and alternates between opening
+    connections and closing them. Every time a connection has
+    been opened, it sends a message.
+
+    \image qmlwebsocketclient-example.webp QML WebSocket Client GUI
+
+    This example opens a window with a welcome message. Every time
+    the window is clicked on, it alternates between opening and
+    closing two connections to an external echo server. The echo
+    server used is at ws.ifelse.io, and an Internet connection is
+    necessary for the example to work. Also TLS must be enabled for
+    the secure connection to work. When the connection is opened or
+    closed, the statusChanged signal is handled by the
+    onStatusChanged handler. Every time the socket is opened, a
+    message is sent, and every time the socket is closed, a message
+    is logged in the window. In addition, there is an
+    onTextMessageReceived handler that logs to the window the
+    messages received from the server.
 */
diff --git a/examples/websockets/doc/qmlwebsocketserver.qdoc b/examples/websockets/doc/qmlwebsocketserver.qdoc
index 83d9831..8582384 100644
--- a/examples/websockets/doc/qmlwebsocketserver.qdoc
+++ b/examples/websockets/doc/qmlwebsocketserver.qdoc
@@ -3,7 +3,18 @@
 
 /*!
     \example qmlwebsocketserver
-    \title QML WebSocket Server Example
+    \title QML WebSocket Server
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
     \brief A simple example that shows how to use a QML WebSocketServer.
+
+    \image qmlwebsocketserver-example.webp QML WebSocket Server GUI
+
+    This example opens a window and has a WebSocketServer listening
+    for incoming connections and a WebSocket connecting to the
+    WebSocketServer. Every time the window is clicked, the WebSocket
+    sends a message to the WebSocketServer. The WebSocketServer has a
+    signal handler that logs the incoming message to the window and
+    sends a message back again, and the WebSocket has a signal
+    handler that logs the returned message to the window.
 */
diff --git a/examples/websockets/doc/simplechat.qdoc b/examples/websockets/doc/simplechat.qdoc
index 646cfe8..907cd30 100644
--- a/examples/websockets/doc/simplechat.qdoc
+++ b/examples/websockets/doc/simplechat.qdoc
@@ -3,12 +3,25 @@
 
 /*!
     \example simplechat
-    \title Simple Chat Example
+    \title Simple WebSocket Chat
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Shows how to use the QWebSocket and QWebSocketServer classes
-    for creating a minimalistic chat application over the WebSocket protocol.
+    \brief A minimal chat application using the WebSocket protocol.
 
-    The Simple Chat Example shows how to use the QWebSocket and QWebSocketServer
-    classes to create a minimalistic chat application over the WebSocket protocol.
+    This application shows how to use the QWebSocket and QWebSocketServer
+    classes to create a minimalist chat application over the WebSocket protocol.
+    The example is a server that allows multiple clients to connect to it to send
+    and receive messages.
+
+    By default it listens at localhost port 1234. It keeps track of all clients
+    that are connected to it, and each time one of the clients sends a message to
+    the server, the message is forwarded to all other clients. When a client
+    disconnects, it is removed from the list of clients.
+
+    \image simplechat-html-example.webp Simple WebSocket Chat HTML Client
+
+    There is also an HTML-client that is used to connect to and disconnect from
+    the server, query about the connection, send messages, and view all the
+    messages sent by other clients.
 
 */
diff --git a/examples/websockets/doc/sslechoclient.qdoc b/examples/websockets/doc/sslechoclient.qdoc
index 16be47e..2136d5f 100644
--- a/examples/websockets/doc/sslechoclient.qdoc
+++ b/examples/websockets/doc/sslechoclient.qdoc
@@ -3,13 +3,25 @@
 
 /*!
     \example sslechoclient
-    \title SSL Echo Client Example
+    \title Secure WebSocket Echo Client
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Shows how to use the QWebSocket class to implement an echo
-    client over a secure connection (wss).
+    \brief A simple client application using secure WebSockets (wss).
 
-    The SSL Echo Client example shows how to use the QWebSocket class to implement
-    an echo client over a secure connection (wss).
+    The Secure WebSocket Echo Client example shows how to use the
+    \l {Qt WebSockets}{WebSocket} class to implement an echo client over
+    a secure connection (wss). It connects to a server and sends a message,
+    and when it receives a message back, it prints it out and exits. SSL
+    support is required for this example to work.
 
-    \sa {Echo Client Example}, {SSL Echo Server Example}
+    This example connects to localhost at port 1234 using a secure connection.
+    Though SSL errors are ignored in this example, this should never be done
+    in production code, because that would leave the client vulnerable to
+    man-in-the-middle attacks. To use a certificates not signed by an existing
+    CA, add a custom self-signed root CA certificate, trust it in your
+    application or system, and sign the server certificate with that.
+
+    \image echoclient-console-example.webp Secure WebSocket Echo Console Client
+
+    \sa {WebSocket Echo Client}, {Secure WebSocket Echo Server}
 */
diff --git a/examples/websockets/doc/sslechoserver.qdoc b/examples/websockets/doc/sslechoserver.qdoc
index bb27b2b..6c3b59a 100644
--- a/examples/websockets/doc/sslechoserver.qdoc
+++ b/examples/websockets/doc/sslechoserver.qdoc
@@ -3,13 +3,29 @@
 
 /*!
     \example sslechoserver
-    \title SSL Echo Server Example
+    \title Secure WebSocket Echo Server
+    \meta category {Networking}
     \ingroup qtwebsockets-examples
-    \brief Shows how to use the QWebSocketServer class for implementing a simple
-    echo server over secure sockets (wss).
+    \brief A simple server to respond to clients over secure WebSockets (wss).
 
-    The SSL Echo Server example shows how to use the QWebSocketServer class
-    to implement a simple echo server over secure sockets (wss).
+    The Secure WebSocket Echo Server example shows how to use the QWebSocketServer
+    class to implement a simple echo server over secure sockets (wss). TLS support
+    is required for this example to work. It authenticates itself to the client
+    and, on success, can accept a message from the client, to which it responds.
+    For the sake of illustration, its response is simply a copy of the message
+    it was sent.
 
-    \sa {SSL Echo Client Example}, {Echo Server Example}
+    The server is configured with a self-signed certificate and key.
+    Unless the client is configured to ignore certificate verification errors,
+    which is not recommenced on production systems, the certificate used by the
+    server must be signed by a custom CA certificate that the client explicitly
+    trusts.
+
+    \image sslechoclient-html-example.webp Secure WebSocket Echo HTML Client
+
+    There is an HTML-based client as part of this example. But it will only
+    work either if the browser used supports the certificate as described above,
+    or if it ignores TLS errors for localhost addresses.
+
+    \sa {Secure WebSocket Echo Client}, {WebSocket Echo Server}
 */