diff options
author | Nico Vertriest <nico.vertriest@digia.com> | 2013-10-01 13:51:33 +0200 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2013-10-14 12:44:21 +0200 |
commit | f674d4a5ade8b24dcb36c3c219c0fd5a842c1bfe (patch) | |
tree | 725cab8f631684432a473ebd00bb8727ccba450c | |
parent | f4474f93b9e0a7df48e94f3fec34a0de64b482bd (diff) |
Doc: language and style review doc qtconnectivity
Reviewed doc Bluetooth and NFC
Task-number: QTBUG-32173
Change-Id: I80f81c2123c3ee4fc269f471123f332dc39ee958
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
-rw-r--r-- | examples/bluetooth/btchat/doc/src/btchat.qdoc | 82 | ||||
-rw-r--r-- | examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc | 4 | ||||
-rw-r--r-- | examples/nfc/poster/doc/src/poster.qdoc | 4 | ||||
-rw-r--r-- | src/bluetooth/doc/src/bluetooth-cpp.qdoc | 4 | ||||
-rw-r--r-- | src/bluetooth/doc/src/bluetooth-overview.qdoc | 8 | ||||
-rw-r--r-- | src/bluetooth/doc/src/bluetooth-qml.qdoc | 6 | ||||
-rw-r--r-- | src/bluetooth/doc/src/examples.qdoc | 13 | ||||
-rw-r--r-- | src/nfc/doc/src/examples.qdoc | 6 | ||||
-rw-r--r-- | src/nfc/doc/src/nfc-cpp.qdoc | 2 | ||||
-rw-r--r-- | src/nfc/doc/src/nfc-index.qdoc | 4 | ||||
-rw-r--r-- | src/nfc/doc/src/nfc-overview.qdoc | 6 | ||||
-rw-r--r-- | src/nfc/doc/src/nfc-qml.qdoc | 4 |
12 files changed, 73 insertions, 70 deletions
diff --git a/examples/bluetooth/btchat/doc/src/btchat.qdoc b/examples/bluetooth/btchat/doc/src/btchat.qdoc index 6f1f040d..77f73fd1 100644 --- a/examples/bluetooth/btchat/doc/src/btchat.qdoc +++ b/examples/bluetooth/btchat/doc/src/btchat.qdoc @@ -34,36 +34,36 @@ \image btchat-example.png - The Bluetooth Chat example implements a simple chat program between multiple parties. The + The Bluetooth Chat example implements a simple chat program between multiple parties. The application always acts as both a server and a client eliminating the need to determine who should connect to whom. \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 ChatServer class. The ChatServer class is declared as: \snippet btchat/chatserver.h declaration The first thing the chat server needs to do is create an instance of QRfcommServer to listen - for incoming Bluetooth connections. Our clientConnected() slot will be called whenever a new + for incoming Bluetooth connections. Our 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 - Discovery Protocol) database. The QBluetoothServiceInfo class encapsulates a service record. + 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 + 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 - UUID that uniquely identifies the service, the discoverability attribute and connection + 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 + The textural description of the service is stored in the ServiceName, ServiceDescription, and ServiceProvider attributes. \snippet btchat/chatserver.cpp Service name, description and provider - Bluetooth uses UUIDs as unique identifiers. Our chat service is uses a randomly generated + Bluetooth uses UUIDs as unique identifiers. The chat service uses a randomly generated UUID. \snippet btchat/chatserver.cpp Service UUID @@ -74,78 +74,78 @@ \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 port that our rfcommServer instance is listening to. + 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. \snippet btchat/chatserver.cpp Protocol descriptor list - Finally we register the service record with the system. + Finally, we register the service record with the system. \snippet btchat/chatserver.cpp Register service - As mentioned earlier incoming connections are handled in the clientConnected() slot. In this - slot we get a pointer a QBluetoothSocket representing the next pending connection connect up - slots to the readyRead() and disconnected() signals and emit a signal to notify others that a - new client has connected. + + 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. \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 + 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. \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 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 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 stop 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 QRfcommServer 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 ChatClient class. The 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 + \e remoteService parameter. Slots are connected to the sockets readyRead(), connected() and disconnected() signals. \snippet btchat/chatclient.cpp startClient - On sucessfull socket connection we emit a signal to notify other. + On successful socket connection we emit a signal to notify others. \snippet btchat/chatclient.cpp connected - Similarily 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 + 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. \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 appended. + 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. \snippet btchat/chatclient.cpp sendMessage - To disconnect from the remote chat service the QBluetoothSocket instance is deleted. + To disconnect from the remote chat service, the QBluetoothSocket instance is deleted. \snippet btchat/chatclient.cpp stopClient \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 + 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: \snippet btchat/chat.h declaration @@ -155,27 +155,27 @@ \snippet btchat/chat.cpp Construct UI We create an instance of the ChatServer and respond to its clientConnected(), - clientDiconnected() and messageReceived() signals. + clientDiconnected(), and messageReceived() signals. \snippet btchat/chat.cpp Create Chat Server - In response to the clientConnected() and clientDisconnected() signals of the ChatServer we - display the typical "foo has joined chat." and "foo has left." messages in the chat session. + 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. \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. + 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 - selected by the user. + 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 + is selected by the user. \snippet btchat/chat.cpp Connect to remote service - In reponse to connected() signals from ChatClient we display the a "Joined chat with foo." + In reponse to the connected() signals from ChatClient, we display the a "Joined chat with X." message in the chat session. \snippet btchat/chat.cpp connected diff --git a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc index 157b3e17..2a84c8b3 100644 --- a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc +++ b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc @@ -29,8 +29,8 @@ \example annotatedurl \title Annotated URL Example -The Annotated URL example displays the contents of specifically formated NDEF messages read from -an NFC Tag. The NDEF message should contain a URI record, an optional image/* MIME record and one +The Annotated URL example displays the contents of specifically formatted NDEF messages read from +an NFC Tag. The NDEF message should contain a URI record, an optional image/* MIME record, and one or more localized Text records. \image annotatedurl.png diff --git a/examples/nfc/poster/doc/src/poster.qdoc b/examples/nfc/poster/doc/src/poster.qdoc index 8d0317c9..125afd95 100644 --- a/examples/nfc/poster/doc/src/poster.qdoc +++ b/examples/nfc/poster/doc/src/poster.qdoc @@ -29,8 +29,8 @@ \example poster \title QML Poster Example -The QML Poster example displays the contents of specifically formated NDEF messages read from an -NFC Tag. The NDEF message should contain a URI record, an optional image/* MIME record and one +The QML Poster example displays the contents of specifically formatted NDEF messages read from an +NFC Tag. The NDEF message should contain a URI record, an optional image/* MIME record, and one or more localized Text records. \image qml-poster-example.png diff --git a/src/bluetooth/doc/src/bluetooth-cpp.qdoc b/src/bluetooth/doc/src/bluetooth-cpp.qdoc index 7bd28c70..9bef246b 100644 --- a/src/bluetooth/doc/src/bluetooth-cpp.qdoc +++ b/src/bluetooth/doc/src/bluetooth-cpp.qdoc @@ -29,10 +29,10 @@ \module QtBluetooth \title Qt Bluetooth C++ Classes -\brief An API enabling basic Bluetooth operations like scanning for devices -and connecting them. +\brief Enables basic Bluetooth operations like scanning for devices and connecting them. \ingroup modules \qtvariable bluetooth +\since 5.2 The \l{Qt Bluetooth} C++ API enables an application to scan for devices and diff --git a/src/bluetooth/doc/src/bluetooth-overview.qdoc b/src/bluetooth/doc/src/bluetooth-overview.qdoc index c101ac34..347ab2cf 100644 --- a/src/bluetooth/doc/src/bluetooth-overview.qdoc +++ b/src/bluetooth/doc/src/bluetooth-overview.qdoc @@ -59,7 +59,7 @@ \section1 Scanning for Bluetooth Devices Similar to the QBluetoothLocalDevice, the API offers QBluetoothDeviceInfo which provides - that information for remote devices. While you can just create QBluetoothDeviceInfo objects on + that information for remote devices. Although you can just create QBluetoothDeviceInfo objects on your own and fill them with data, the easier way is to use the QBluetoothDeviceDiscoveryAgent to start an automated search for visible Bluetooth devices within the connectable range. @@ -69,7 +69,7 @@ Once the desired device is found, there are two main use cases provided by Qt Bluetooth. The simpler is to send files via the Obex Object Push Profile (OPP). As the name describes, this - profile can only push files from one device to another but not pull files or browse the remote + profile can only push files from one device to another, but not pull files or browse the remote file system. Because of this limitation, this profile does not require the two devices to be paired before exchanging data. To push files to remote devices, create a QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in @@ -79,7 +79,7 @@ \section1 Exchanging Data Between Devices - The more flexible approach to do communication between two Bluetooth enabled devices, is to + The more flexible approach for communication between two Bluetooth enabled devices, is to create a virtual serial port connection and freely exchange data over that connection. This can be done by the Serial Port Profile (SPP). The Serial Port Profile emulates a serial connection over the Bluetooth transport protocol RFCOMM. @@ -95,7 +95,7 @@ \snippet btchat/chatclient.cpp startClient Using such a connection allows to exchange any form of data in both directions. - It is perfectly suited for use cases like gaming or syncing the state between two instances of + It is perfectly suited for gaming or for syncing the state between two instances of an application on two devices. For more detailed descriptions on how to configure the server and client, please refer to the detailed description sections in the QRfcommServer and QBluetoothSocket classes. A good example to start with SPP is the \l{btchat}{Bluetooth Chat} diff --git a/src/bluetooth/doc/src/bluetooth-qml.qdoc b/src/bluetooth/doc/src/bluetooth-qml.qdoc index f9ff3d30..9c9fe0aa 100644 --- a/src/bluetooth/doc/src/bluetooth-qml.qdoc +++ b/src/bluetooth/doc/src/bluetooth-qml.qdoc @@ -31,10 +31,10 @@ \qmlmodule QtBluetooth 5.2 \title Qt Bluetooth QML Types \ingroup qmlmodules -\brief Provides QML types for basic Bluetooth operations on devices +\brief Provides QML types for basic Bluetooth operations on devices. -The Qt Bluetooth QML Types enable an application to scan for devices and connect and -interact with them in an easier way than the C++ Classes. However, it is a bit +The Qt Bluetooth QML Types enable an application to scan for devices and connect +and interact with them in an easier way than the C++ Classes. However, it is a bit more limited than the C++ API. You can always use the C++ API to create QML plugins with the flexibility you need. diff --git a/src/bluetooth/doc/src/examples.qdoc b/src/bluetooth/doc/src/examples.qdoc index ec98dbc5..8884b3c8 100644 --- a/src/bluetooth/doc/src/examples.qdoc +++ b/src/bluetooth/doc/src/examples.qdoc @@ -29,12 +29,15 @@ \ingroup all-examples \page bluetooth-examples.html \title Qt Bluetooth Examples - \brief Examples for the QtBluetooth module + \brief Examples for the QtBluetooth module. - This is a variety of examples that cover the entire range of the the Qt Bluetooth API. You will find them in their own documentation but are also accessible from here. + This is a variety of examples that cover the entire range of the the Qt + Bluetooth API. You will find them in their own documentation but they are also + accessible from here. \section2 C++ Tutorial - The \l{btchat}{Bluetooth Chat} example contains a tutorial on how to use the C++ API to create a RFCOMM server and client and exchange data between them. + The \l{btchat}{Bluetooth Chat} example contains a tutorial on how to use the + C++ API to create a RFCOMM server and client, and exchange data between them. \section2 C++ Examples \table 80% @@ -60,8 +63,8 @@ \li Description \row \li \l{bttennis}{QML Bluetooth Tennis} - \li The tennis game using a QML interface to the Bluetooth API. It must connect to an - instance of the C++ \l{bttennis}{Bluetooth Tennis} game to play. + \li The tennis game using a QML interface to the Bluetooth API. It + must connect to an instance of the C++ \l{bttennis}{Bluetooth Tennis} game to play. \row \li \l{btscanner}{QML Bluetooth Scanner} \li A QML implementation of the Bluetooth device scanner. diff --git a/src/nfc/doc/src/examples.qdoc b/src/nfc/doc/src/examples.qdoc index f49c0d8f..1f473991 100644 --- a/src/nfc/doc/src/examples.qdoc +++ b/src/nfc/doc/src/examples.qdoc @@ -29,10 +29,10 @@ \ingroup all-examples \page nfc-examples.html \title Qt NFC Examples -\brief Examples for the QtNfc module +\brief Examples for the QtNfc module. -This is a variety of examples that cover the entire range of the the Qt NFC API. You will find them -in their own documentation but are also accessible from here. +This is a variety of examples that cover the entire range of the Qt NFC API. You will find them +in their own documentation, but they are also accessible from here. \section2 C++ Tutorial diff --git a/src/nfc/doc/src/nfc-cpp.qdoc b/src/nfc/doc/src/nfc-cpp.qdoc index b52db05b..4df93e69 100644 --- a/src/nfc/doc/src/nfc-cpp.qdoc +++ b/src/nfc/doc/src/nfc-cpp.qdoc @@ -33,7 +33,7 @@ \title Qt NFC C++ Classes \brief An API for accessing NFC Forum Tags. -The \l{Qt NFC} C++ API enables an application to access NFC Forum Tagss. +The \l{Qt NFC} C++ API enables an application to access NFC Forum Tags. To use the C++ library in your application, add the following configuration option to your \c .pro file: diff --git a/src/nfc/doc/src/nfc-index.qdoc b/src/nfc/doc/src/nfc-index.qdoc index a353a759..7309e4cc 100644 --- a/src/nfc/doc/src/nfc-index.qdoc +++ b/src/nfc/doc/src/nfc-index.qdoc @@ -28,10 +28,10 @@ /*! \page qtnfc-index.html \title Qt NFC -\brief Qt NFC enables connectivity between NFC enabled devices. +\brief Enables connectivity between NFC enabled devices. NFC is an extremely short-range (less than 20 centimeters) wireless technology and has a -maximum transfer rate of 424 kbit/s. NFC is ideal for transferring small packets of data when two +maximum transfer rate of 424 kbit/s. NFC is ideal for transferring small packets of data when two devices are touched together. The NFC API provides APIs for interacting with NFC Forum Tags and NFC Forum Devices, including diff --git a/src/nfc/doc/src/nfc-overview.qdoc b/src/nfc/doc/src/nfc-overview.qdoc index 6c479c62..25e193a6 100644 --- a/src/nfc/doc/src/nfc-overview.qdoc +++ b/src/nfc/doc/src/nfc-overview.qdoc @@ -29,14 +29,14 @@ \ingroup technology-apis \title Qt NFC Overview \page qtnfc-overview.html -\brief The Qt NFC classes provides access to NFC enabled devices. +\brief Provides access to NFC enabled devices. \tableofcontents With the Qt NFC API typical use cases are: \list - \li Detect NFC tags entering and leaving communication range. + \li Detect NFC tags entering and leaving the communication range. \li Read and write NDEF message on NFC Forum Tags. \li Register an NDEF message handler for a particular content type. \endlist @@ -44,6 +44,6 @@ With the Qt NFC API typical use cases are: The following sections describe how to use QtNfc C++ classes for the above use cases. \section1 Detect NFC tags entering and leaving communication range. -\section1 Read and write NDEF message on NFC Forum Tags. +\section1 Read and write an NDEF message on NFC Forum Tags. \section1 Register an NDEF message handler for a particular content type. */ diff --git a/src/nfc/doc/src/nfc-qml.qdoc b/src/nfc/doc/src/nfc-qml.qdoc index a8151bba..42e57159 100644 --- a/src/nfc/doc/src/nfc-qml.qdoc +++ b/src/nfc/doc/src/nfc-qml.qdoc @@ -31,9 +31,9 @@ \qmlmodule QtNfc 5.2 \title Qt NFC QML Types \ingroup qmlmodules -\brief Provides QML types for accessing NFC Forum Tags +\brief Provides QML types for accessing NFC Forum Tags. -To use the classes of the module in your application you need the following +To use the classes of the module in your application, you need the following import statement in your \c .qml file: \snippet doc_src_qtnfc.qml import |