Final review and grammatical changes

features/FEATURE_BLE/targets/TARGET_CORDIO/doc/PortingGuide.md

@@ -41,17 +41,18 @@ Include an HCI driver for the BLE module used by the target, and a factory funct
 
 1. Navigate to the folder of the BLE API that hosts the target port `features/FEATURE_BLE/targets`.
 
-1. Create a folder containing the port code to isolate it from other code. Begin this folder's name with `TARGET_` and the rest of the name in capital letters.
+1. Create a folder containing the port code to isolate it from other code.
+  * Begin this folder's name with `TARGET_` and the rest of the name in capital letters.
 
 #### Create the HCI driver
 
-The HCI driver is split in two entities. One handles HCI communication with the Bluetooth module. The other handles initialization, reset sequence, and memory dedicated to the Bluetooth controller.
+The HCI driver is split into two entities. One handles HCI communication with the Bluetooth module. The other handles the initialization, reset sequence, and memory dedicated to the Bluetooth controller.
 
 More information about the architecture can be found in [HCI abstraction architecture](HCIAbstraction.md).
 
 #### HCITransport
 
-<span class="notes">**Note:** If the Bluetooth controller uses an H4 communication interface and the host exposes serial flow control in Mbed, then you can skip this step. Use the class `ble::vendor::cordio::H4TransportDriver` as the transport driver.</span>
+<span class="notes">**Note:** If the Bluetooth controller uses an H4 communication interface and the host exposes serial flow control in Mbed, you can skip this step. Use the class `ble::vendor::cordio::H4TransportDriver` as the transport driver.</span>
 
 To code an empty transport driver:
 
@@ -85,9 +86,11 @@ private:
 
 It inherits publicly from the base class `CordioHCITransportDriver`.
 
+##### Functions
+
 * **Initialization/termination**: The functions `initialize` and `terminate` are responsible for initializing and terminating the transport driver. It is not necessary to initialize the transport in the constructor.
 
-* **Sending data**: The function `write` sends data in input to the Bluetooth controller and return the number of bytes in the `data` buffer sent. Depending on the type of transport you implement, you may need to send the packet `type` to the controller before the packet data.
+* **Sending data**: The function `write` sends data as input to the Bluetooth controller and returns the number of bytes in the `data` buffer sent. Depending on the type of transport you implement, you may need to send the packet `type` to the controller before the packet data.
 
 * **Receiving data**: Inject HCI data from the Bluetooth controller to the system by calling `on_data_received`. This is a static function provided by the base class.
 
@@ -239,20 +242,17 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
         case HCI_OPCODE_RESET:
             /* initialize rand command count */
             randCnt = 0;
-            // Set the event mask to control which events are generated by the
+            // Set the event mask to control which events are generated by the controller for the host.
-            // controller for the host.
             HciSetEventMaskCmd((uint8_t *) hciEventMask);
             break;
 
         case HCI_OPCODE_SET_EVENT_MASK:
-            // Set the event mask to control which LE events are generated by
+            // Set the event mask to control which LE events are generated by the controller for the host.
-            // the controller for the host.
             HciLeSetEventMaskCmd((uint8_t *) hciLeEventMask);
             break;
 
         case HCI_OPCODE_LE_SET_EVENT_MASK:
-            // Set the event mask to control which events are generated by the
+            // Set the event mask to control which events are generated by the controller for the host (2nd page of flags).
-            // controller for the host (2nd page of flags).
             HciSetEventMaskPage2Cmd((uint8_t *) hciEventMaskPage2);
             break;
 
@@ -277,24 +277,20 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
             /* initialize ACL buffer accounting */
             hciCoreCb.availBufs = hciCoreCb.numBufs;
 
-            // Read the states and state combinations supported by the link
+            // Read the states and state combinations supported by the link layer of the controller.
-            // layer of the controller.
             HciLeReadSupStatesCmd();
             break;
 
         case HCI_OPCODE_LE_READ_SUP_STATES:
-            // Store supported state and combination in the runtime parameters
+            // Store supported state and combination in the runtime parameters of the stack.
-            // of the stack.
             memcpy(hciCoreCb.leStates, pMsg, HCI_LE_STATES_LEN);
 
-            // Read the total of whitelist entries that can be stored in the
+            // Read the total of whitelist entries that can be stored in the controller.
-            // controller.
             HciLeReadWhiteListSizeCmd();
             break;
 
         case HCI_OPCODE_LE_READ_WHITE_LIST_SIZE:
-            // Store the number of whitelist entries in the stack runtime
+            // Store the number of whitelist entries in the stack runtime parameters.
-            // parameters.
             BSTREAM_TO_UINT8(hciCoreCb.whiteListSize, pMsg);
 
             // Read the LE features supported by the controller.
@@ -305,18 +301,15 @@ void HCIDriver::handle_reset_sequence(uint8_t *pMsg) {
             // Store the set of LE features supported by the controller.
             BSTREAM_TO_UINT16(hciCoreCb.leSupFeat, pMsg);
 
-            // Read the total number of address translation entries which can be
+            // Read the total number of address translation entries which can be stored in the controller resolving list.
-            // stored in the controller resolving list.
             hciCoreReadResolvingListSize();
             break;
 
         case HCI_OPCODE_LE_READ_RES_LIST_SIZE:
-            // Store the number of address translation entries in the stack
+            // Store the number of address translation entries in the stack runtime parameter.
-            // runtime parameter.
             BSTREAM_TO_UINT8(hciCoreCb.resListSize, pMsg);
 
-            // Read the Controller’s maximum supported payload octets and packet
+            // Read the Controller’s maximum supported payload octets and packet duration times for transmission and reception.
-            // duration times for transmission and reception.
             hciCoreReadMaxDataLen();
             break;
 
@@ -450,7 +443,7 @@ ble::vendor::cordio::CordioHCIDriver& ble_cordio_get_hci_driver() {
 
 ### Tests
 
-We bundle Greentea tests with the Cordio port of the BLE API, so the transport driver works, as well as validation of Cordio stack initialization. You can run these tests with the following command:
+We bundle Greentea tests with the Cordio port of the BLE API, so the transport driver and validation of Cordio stack initialization both work. You can run these tests with the following command:
 
 ```
 mbed test -t <toolchain> -m <target> -n mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-driver,mbed-os-features-feature_ble-targets-target_cordio-tests-cordio_hci-transport