Doc: Review QtSerialPort documentation

Adapted to review comments

Task-number: QTBUG-32173

Change-Id: I41839934c3aea9ccf3ef596e2a869b479f3c75ba
Reviewed-by: Laszlo Papp <lpapp@kde.org>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

2 files changed, 67 insertions, 69 deletions

diff --git a/examples/serialport/doc/blockingmaster.qdoc b/examples/serialport/doc/blockingmaster.qdoc
index 4bf4b864..1ce649a5 100644
--- a/examples/serialport/doc/blockingmaster.qdoc
+++ b/examples/serialport/doc/blockingmaster.qdoc
@@ -29,11 +29,12 @@
     \example blockingmaster
     \title Blocking Master Example
     \ingroup qtserialport-examples
+    \brief Explains how to create an app using QSerialPort's synchronous API.
 
-    The Blocking Master example shows how to create a application for a
-    serial interface using QSerialPort's synchronous API in a non-GUI thread.
+    The blocking master example shows how to create an application for a
+    serial interface using QSerialPort's synchronous API in a worker thread.
 
-    \image blockingmaster-example.png Screenshot of the Blocking Master example
+    \image blockingmaster-example.png Screenshot of the blocking master example
 
     QSerialPort supports two general programming approaches:
 
@@ -45,16 +46,15 @@
     returns immediately. When the data is sent to the serial port, QSerialPort
     emits \l{QIODevice::bytesWritten()}{bytesWritten()}.
 
-    \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded
-    applications, the \c waitFor...() functions can be called (i.e.
+    \li \e{The synchronous (blocking) approach.} In headless and multithreaded
+    applications, the wait functions can be called (in this case,
     QSerialPort::waitForReadyRead()) to suspend the calling thread until the
     operation has completed.
 
     \endlist
 
-    In this example, the synchronous approach is demonstrated. The
-    \l{terminal}{Terminal} example illustrates the
-    asynchronous approach.
+    In this example, the synchronous approach is demonstrated. The \l{terminal}{Terminal}
+    example illustrates the asynchronous approach.
 
     The purpose of this example is to demonstrate a pattern that you can use
     to simplify your serial programming code, without losing responsiveness
@@ -64,11 +64,11 @@
     But contrary to what many think, using threads with QThread does not
     necessarily add unmanagable complexity to your application.
 
-    This application is a Master, that demonstrate the work paired with Slave
+    This application is the master which demonstrates the work paired with the slave
     application \l{blockingslave}{Blocking Slave Example}.
 
-    The Master application is initiate the transfer request via serial port to
-    the Slave application and wait for a response from it.
+    The master application initiates the transfer request via the serial port to
+    the slave application and waits for response.
 
     We will start with the MasterThread class, which handles the serial
     programming code.
@@ -76,85 +76,85 @@
     \snippet blockingmaster/masterthread.h 0
 
     MasterThread is a QThread subclass that provides an API for scheduling
-    requests to Slave, and it has signals for delivering responses and reporting
-    errors. You can call transaction() to startup new master transaction with
-    desired request data and other parameters, and the result is delivered by
-    the response() signal. If any error occurs, the error() or timeout() signals
-    is emitted.
-
-    It's important to notice that transaction() is called from the main, GUI
-    thread, but the request data and other parameters will be accessed from
-    MasterThread's thread. Because we will be reading and writing MasterThread's
-    data members from different threads concurrently, we use QMutex to
-    synchronize access.
+    requests to the slave, and it has signals for delivering responses and reporting
+    errors. The transaction() method can be called to startup the new master
+    transaction with the desired request data and other parameters. The result
+    is delivered by the response() signal. If any error occurs, the error() or
+    timeout() signal is emitted.
+
+    It's important to notice that the transaction() method is called from the main,
+    GUI thread, but the request data and other parameters will be accessed from
+    MasterThread's thread. Since the MasterThread data members will be read and
+    written concurrently from different threads, QMutex is used to synchronize
+    the access.
 
     \snippet blockingmaster/masterthread.cpp 2
 
     The transaction() function stores the serial port name, timeout and request
-    data, and we lock the mutex with QMutexLocker to protect this data. We then
-    start the thread, unless it is already running. We will come back to the
-    QWaitCondition::wakeOne() call later.
+    data. The mutex can be locked with QMutexLocker to protect this data. Then,
+    the thread can be started, unless it is already running. QWaitCondition::wakeOne()
+    will be discussed later.
 
     \snippet blockingmaster/masterthread.cpp 4
     \snippet blockingmaster/masterthread.cpp 5
 
-    In the run() function, we start by acquiring the mutex lock, fetching the
+    In the run() function, start by acquiring the mutex lock, fetch the
     serial port name, timeout and request data from the member data, and then
-    releasing the lock again. The case that we are protecting ourselves against
-    is that \c transaction() could be called at the same time as we are fetching
-    this data. QString is reentrant but not thread-safe, and we must
-    also avoid the unlikely risk of reading the serial port name from one request,
-    and timeout or request data of another. And as you might have guessed,
-    MasterThread can only handle one request at a time.
+    release the lock again.
+
+    Under no circumstance should the method \c transaction() be called simultaneously
+    with a process fetching these data. QString is reentrant but not thread-safe, and
+    it is not recommended to read the serial port name from one request,
+    and timeout or request data from another. The MasterThread can only handle
+    one request at a time.
 
     The QSerialPort object we construct on stack into run() function before loop
     enter:
 
     \snippet blockingmaster/masterthread.cpp 6
 
-    This allows us once to create an object, while running loop, and also means
+    This allows us once to create an object, while running the loop, and also means
     that all the methods of the object will be executed in the context of the
     run() thread.
 
-    In the loop, we check for changed or not the name of serial port for the
-    current transaction. And if the name is changed then re-open and re-configure
-    the serial port.
+    In the loop, check whether the name of the serial port for the current trans-
+    action has changed or not. If it has, reopen and reconfigure the serial port.
 
     \snippet blockingmaster/masterthread.cpp 7
 
-    The loop will continue creating request data, write to serial port and wait
+    The loop will continue to request data, write to the serial port and wait
     until all data is transferred.
 
     \snippet blockingmaster/masterthread.cpp 8
 
     \warning The method waitForBytesWritten() should be used after each write()
     call for the blocking approach, because it processes all the I/O routines
-    instead of Qt event-loop.
+    instead of the Qt event loop.
 
-    The timeout() signal is emitted if error occurs when transferring data.
+    The timeout() signal is emitted if an error occurs when transferring data.
 
     \snippet blockingmaster/masterthread.cpp 9
 
-    After a successful request, we start wait until response and try read it.
+    After a successful request, wait for a response, and then try to read it.
 
     \snippet blockingmaster/masterthread.cpp 10
 
     \warning The method waitForReadyRead() should be used before each read()
     call for the blocking approach, because it processes all the I/O routines
-    instead of Qt event-loop.
+    instead of Qt event loop.
 
-    The timeout() signal is emitted if error occurs when receiving data.
+    The timeout() signal is emitted if an error occurs when receiving data.
 
     \snippet blockingmaster/masterthread.cpp 11
 
-    After a successful transaction is emitted response() signal containing the
-    data received from the Slave application:
+    When a transaction has been completed successfully, the response() signal contains
+    the data received from the slave application:
 
     \snippet blockingmaster/masterthread.cpp 12
 
-    Next, the thread goes to sleep until the next transaction is appear. On
-    waking, the thread re-reads the new data of members and run loop from the
-    beginning.
+    Next, the thread goes to sleep until the next transaction has appeared. On
+    waking, the thread re-reads the new data from the members and runs the
+    loop from the beginning.
 
     \snippet blockingmaster/masterthread.cpp 13
 
diff --git a/examples/serialport/doc/blockingslave.qdoc b/examples/serialport/doc/blockingslave.qdoc
index 95690dcd..c98080d9 100644
--- a/examples/serialport/doc/blockingslave.qdoc
+++ b/examples/serialport/doc/blockingslave.qdoc
@@ -87,28 +87,27 @@
 
     It's important to notice that startSlave() is called from the main, GUI
     thread, but the response data and other parameters will be accessed from
-    SlaveThread's thread. Because we will be reading and writing SlaveThread's
-    data members from different threads concurrently, we use QMutex to
+    SlaveThread's thread. SlaveThread's data members are read and written
+    from different threads concurrently, so it is advisable to use QMutex to
     synchronize access.
 
     \snippet blockingslave/slavethread.cpp 2
 
     The startSlave() function stores the serial port name, timeout and response
-    data, and we lock the mutex with QMutexLocker to protect this data. We then
-    start the thread, unless it is already running. We will come back to the
-    QWaitCondition::wakeOne() call later.
+    data, and QMutexLocker locks the mutex to protect these data. We then
+    start the thread, unless it is already running. QWaitCondition::wakeOne()
+    will be discussed later.
 
     \snippet blockingslave/slavethread.cpp 4
     \snippet blockingslave/slavethread.cpp 5
 
-    In the run() function, we start by acquiring the mutex lock, fetching the
+    In the run() function, start by acquiring the mutex lock, fetch the
     serial port name, timeout and response data from the member data, and then
-    releasing the lock again. The case that we are protecting ourselves against
-    is that \c startSlave() could be called at the same time as we are fetching
-    this data. QString is reentrant but not thread-safe, and we must
-    also avoid the unlikely risk of reading the serial port name from one startup,
-    call and timeout or response data of another. And as you might have guessed,
-    SlaveThread can only handle one startup at a time.
+    release the lock again. Under no circumstance should the method \c startSlave()
+    be called simultaneously with a process fetching these data. QString is reentrant
+    but not thread-safe, and it is not recommended to read the serial port name
+    from one startup, call and timeout or response data of another.  SlaveThread
+    can only handle one startup at a time.
 
     The QSerialPort object we construct on stack into run() function before loop
     enter:
@@ -119,13 +118,12 @@
     that all the methods of the object will be executed in the context of the
     run() thread.
 
-    In the loop, we check for changed or not the name of serial port for the
-    current startup. And if the name is changed then re-open and re-configure
-    the serial port.
+    In the loop, check whether the name of the serial port for the current
+    startup has changed or not. If it has, re-open and reconfigure the serial port.
 
     \snippet blockingslave/slavethread.cpp 7
 
-    The loop will continue wait for reading request data:
+    The loop will continue waiting for request data:
 
     \snippet blockingslave/slavethread.cpp 8
 
@@ -137,7 +135,7 @@
 
     \snippet blockingslave/slavethread.cpp 9
 
-    After a successful read, we try send response and wait completion of the
+    After a successful read, try to send a response and wait for completion of the
     transfer:
 
     \snippet blockingslave/slavethread.cpp 10
@@ -146,18 +144,18 @@
     call for the blocking approach, because it processes all the I/O routines
     instead of Qt event-loop.
 
-    The timeout() signal is emitted if error occurs when writing data.
+    The timeout() signal is emitted if an error occurs when writing data.
 
     \snippet blockingslave/slavethread.cpp 11
 
-    After a successful writing is emitted request() signal containing the
+    After a successful writing is emitted, request() signal containing the
     data received from the Master application:
 
     \snippet blockingslave/slavethread.cpp 12
 
-    Next, the thread goes to re-reads the current parameters for serial interface,
-    because they can be updated when new startSlave() and run loop from the
-    beginning.
+    Next, the thread switches to reading the current parameters for the serial
+    interface, because they can already have been updated, and run the loop
+    from the beginning.
 
     \snippet blockingslave/slavethread.cpp 13