From 122513bd1a9ad5324bf37269ce7dd59d265ecf29 Mon Sep 17 00:00:00 2001 From: Ivan Solovev Date: Thu, 16 Mar 2023 18:32:12 +0100 Subject: BtChat example: revamp documentation * Remove 'Example' from the name * Add 'Connectivity' category * Consistently use \c for class and method names * Add some link to QBluetoothSocket's methods * Fix some typos As a drive-by: wrap lines at 80 characters in places where other changes were made to the docs. Task-number: QTBUG-111972 Change-Id: Idbe34bde04510f7319d58e33ce52fd8324ddf868 Reviewed-by: Juha Vuolle (cherry picked from commit 7d20a4fb6a520b13666c8808ae74fb9a43b6532c) Reviewed-by: Qt Cherry-pick Bot --- examples/bluetooth/btchat/doc/src/btchat.qdoc | 119 +++++++++++++++----------- 1 file changed, 67 insertions(+), 52 deletions(-) diff --git a/examples/bluetooth/btchat/doc/src/btchat.qdoc b/examples/bluetooth/btchat/doc/src/btchat.qdoc index 078fb05f..7469a5af 100644 --- a/examples/bluetooth/btchat/doc/src/btchat.qdoc +++ b/examples/bluetooth/btchat/doc/src/btchat.qdoc @@ -3,11 +3,12 @@ /*! \example btchat - \title Bluetooth Chat Example - \brief An example showing communication through Bluetooth. + \title Bluetooth Chat + \meta category {Connectivity} + \brief Shows communication through Bluetooth using RFCOMM protocol. The Bluetooth Chat example shows how to use the \l{Qt Bluetooth} API to communicate - with another application on a remote device using Bluetooth. + with another application on a remote device using Bluetooth RFCOMM protocol. \image btchat-example.png @@ -19,26 +20,28 @@ \section1 Chat Server - The chat server is implemented by the ChatServer class. The ChatServer class is declared as: + The chat server is implemented by the \c ChatServer class. + The \c ChatServer class is declared as: \snippet btchat/chatserver.h declaration - The first thing the chat server needs to do is create an instance of QBluetoothServer to listen - for incoming Bluetooth connections. Our clientConnected() slot will be called whenever a new - connection is created. + The first thing the chat server needs to do is create an instance of + QBluetoothServer to listen for incoming Bluetooth connections. The + \c {clientConnected()} slot will be called whenever a new connection is + created. \snippet btchat/chatserver.cpp Create the server The chat server is only useful if others know that it is there. To enable other devices to - discover it, a record describing the service needs to be published in the systems SDP (Service + discover it, a record describing the service needs to be published in the system's SDP (Service Discovery Protocol) database. The QBluetoothServiceInfo class encapsulates a service record. - We will publish a service record that contains some textural descriptions of the services, a + We will publish a service record that contains some textual descriptions of the services, a UUID that uniquely identifies the service, the discoverability attribute, and connection parameters. - The textural description of the service is stored in the ServiceName, ServiceDescription, and - ServiceProvider attributes. + The textual description of the service is stored in the \c {ServiceName}, + \c {ServiceDescription}, and \c {ServiceProvider} attributes. \snippet btchat/chatserver.cpp Service name, description and provider @@ -48,13 +51,14 @@ \snippet btchat/chatserver.cpp Service UUID \snippet btchat/chatserver.cpp Service UUID set - A Bluetooth service is only discoverable if it is in the PublicBrowseGroup. + A Bluetooth service is only discoverable if it is in the + \l {QBluetoothUuid::}{PublicBrowseGroup}. \snippet btchat/chatserver.cpp Service Discoverability - The ProtocolDescriptorList attribute is used to publish the connection parameters that the - remote device requires to connect to our service. Here we specify that the Rfcomm protocol is - used and set the port number to the port that our rfcommServer instance is listening to. + The \c ProtocolDescriptorList attribute is used to publish the connection parameters that the + remote device requires to connect to our service. Here we specify that the \c Rfcomm protocol + is used and set the port number to the port that our \c rfcommServer instance is listening to. \snippet btchat/chatserver.cpp Protocol descriptor list @@ -62,58 +66,64 @@ \snippet btchat/chatserver.cpp Register service - - As mentioned earlier, incoming connections are handled in the clientConnected() slot where - pending connections are connected to the readyRead() and disconnected() signals. The signals - notify others that a new client has connected. + As mentioned earlier, incoming connections are handled in the + \c {clientConnected()} slot where pending connections are connected to the + \l {QBluetoothSocket::}{readyRead()} and + \l {QBluetoothSocket::}{disconnected()} signals. The signals notify others + that a new client has connected. \snippet btchat/chatserver.cpp clientConnected - The readSocket() slot is called whenever data is ready to be read from a client socket. The - slot reads individual lines from the socket, converts them from UTF-8, and emits the - messageReceived() signal. + The \c {readSocket()} slot is called whenever data is ready to be read from + a client socket. The slot reads individual lines from the socket, converts + them from UTF-8, and emits the \c {messageReceived()} signal. \snippet btchat/chatserver.cpp readSocket - The clientDisconnected() slot is called whenever a client disconnects from the service. The - slot emits a signal to notify others that a client has disconnected, and deletes the socket. + The \c {clientDisconnected()} slot is called whenever a client disconnects + from the service. The slot emits a signal to notify others that a client + has disconnected, and deletes the socket. \snippet btchat/chatserver.cpp clientDisconnected - The sendMessage() slot is used to send a message to all connected clients. The message is + The \c {sendMessage()} slot is used to send a message to all connected clients. The message is converted into UTF-8 and appended with a newline before being sent to all clients. \snippet btchat/chatserver.cpp sendMessage - When the chat server is stopped the service record is removed from the system SDP database, all - connected client sockets are deleted, and the QRfcommServer instance is deleted. + When the chat server is stopped, the service record is removed from the + system SDP database, all connected client sockets are deleted, and the + \c rfcommServer instance is deleted. \snippet btchat/chatserver.cpp stopServer \section1 Chat Client - The chat client is implemented by the ChatClient class. The ChatClient class is declared as: + The chat client is implemented by the \c ChatClient class. + The \c ChatClient class is declared as: \snippet btchat/chatclient.h declaration - The client creates a new QBluetoothSocket and connects to the remote service described by the - \e remoteService parameter. Slots are connected to the sockets readyRead(), connected() and - disconnected() signals. + The client creates a new QBluetoothSocket and connects to the remote + service described by the \c remoteService parameter. Slots are connected + to the socket's \l {QBluetoothSocket::}{readyRead()}, + \l {QBluetoothSocket::}{connected()}, and + \l {QBluetoothSocket::}{disconnected()} signals. \snippet btchat/chatclient.cpp startClient - On successful socket connection we emit a signal to notify others. + On successful socket connection we emit a signal to notify other users. \snippet btchat/chatclient.cpp connected - Similarly to the chat server, the readSocket() slot is called when data is available from the - socket. Lines are read individually and converted from UTF-8. The messageReceived() signal - is emitted. + Similarly to the chat server, the \c readSocket() slot is called when data + is available from the socket. Lines are read individually and converted + from UTF-8. The \c {messageReceived()} signal is emitted. \snippet btchat/chatclient.cpp readSocket - The sendMessage() slot is used to send a message to the remote device. The message is - converted to UTF-8 and a newline is appended. + The \c {sendMessage()} slot is used to send a message to the remote device. + The message is converted to UTF-8 and a newline is appended. \snippet btchat/chatclient.cpp sendMessage @@ -123,9 +133,10 @@ \section1 Chat Dialog - The main window of this example is the chat dialog, implemented in the Chat class. This class - displays a chat session between a single ChatServer and zero or more ChatClients. The Chat - class is declared as: + The main window of this example is the chat dialog, implemented in the + \c Chat class. This class displays a chat session between a single + \c ChatServer and zero or more \c {ChatClient}s. The \c Chat class is + declared as: \snippet btchat/chat.h declaration @@ -133,38 +144,42 @@ \snippet btchat/chat.cpp Construct UI - We create an instance of the ChatServer and respond to its clientConnected(), - clientDiconnected(), and messageReceived() signals. + We create an instance of the \c ChatServer and respond to its + \c {clientConnected()}, \c {clientDiconnected()}, and + \c {messageReceived()} signals. \snippet btchat/chat.cpp Create Chat Server - In response to the clientConnected() and clientDisconnected() signals of the ChatServer, we - display the typical "X has joined chat." and "Y has left." messages in the chat session. + In response to the \c {clientConnected()} and \c {clientDisconnected()} + signals of the \c ChatServer, we display the typical "X has joined chat." + and "Y has left." messages in the chat session. \snippet btchat/chat.cpp clientConnected clientDisconnected - Incoming messages from clients connected to the ChatServer are handled in the showMessage() - slot. The message text tagged with the remote device name is displayed in the chat session. + Incoming messages from clients connected to the \c ChatServer are handled + in the \c {showMessage()} slot. The message text tagged with the remote + device name is displayed in the chat session. \snippet btchat/chat.cpp showMessage In response to the connect button being clicked, the application starts service discovery and - presents a list of discovered chat services on remote devices. A ChatClient for the service + presents a list of discovered chat services on remote devices. A \c ChatClient for the service is selected by the user. \snippet btchat/chat.cpp Connect to remote service - In reponse to the connected() signals from ChatClient, we display the a "Joined chat with X." - message in the chat session. + In reponse to the \c {connected()} signals from \c ChatClient, we display + the "Joined chat with X." message in the chat session. \snippet btchat/chat.cpp connected - Messages are sent to all remote devices via the ChatServer and ChatClient instances by emitting - the sendMessage() signal. + Messages are sent to all remote devices via the \c ChatServer and + \c ChatClient instances by emitting the \c {sendMessage()} signal. \snippet btchat/chat.cpp sendClicked - We need to clean up ChatClient instances when the remote device forces a disconnect. + We need to clean up \c ChatClient instances when the remote device forces + a disconnect. \snippet btchat/chat.cpp clientDisconnected */ -- cgit v1.2.1