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}
 */