Add more comments to Gap.proto

Author: oguzcanoguz

services/ble/Gap.proto

@@ -103,6 +103,7 @@ message AddressWithType
     AddressType addressType = 2;
 }
 
+// TODO: See if we can merge this with AdvertisementType
 message AdvertisingEventType
 {
     enum AdvertisingEventTypeEnum
@@ -182,7 +183,6 @@ message SecurityPreference
     SupportEnum secureConnections = 1;
     SupportEnum mitm = 2;
     IoCapabilitiesEnum ioCapabilities = 3;
-    bool outOfBandSupported = 4;
 }
 
 // ==================================================
@@ -192,7 +192,7 @@ message SecurityPreference
 //  Unless otherwise specified, all methods are allowed in all link layer states
 // Callback constraints:
 //  Unless otherwise specified, methods do not by default result in any callbacks on the response service
-//  When a callback is specified for a method and only for that method, next of the same method call is not allowed until the callback has been received
+//  When a callback is specified for a method and only for that method, another call of the same method is not allowed until the callback has been received.
 //  When a callback is specified for more than one method, any of the associated method calls is not allowed until the callback for the previous call have been received
 // ==================================================
 service GapPeripheral
@@ -217,15 +217,17 @@ service GapPeripheral
     // Allowed in link layer states: standby
     // Formatting of advertisement data is as per Bluetooth Core Specification.
     // TODO: Include ble spec reference
-    // Maximum advertisement data length is 28 bytes. Server adds 3 more bytes of flags data with the flag bits 'LE General Discoverable Mode' and 'BR/EDR Not Supported' enabled.
+    // Maximum advertisement data length for this method is 28 bytes. Server reserves 3 bytes for flags data with the flag bits 'LE General Discoverable Mode' and 'BR/EDR Not Supported' enabled.
     // Server will not check validity of the advertisement data and only maximum length of each field will be passed to BLE stack
+    // If not set by this method, server will have aa advertisement data only flags field.
     rpc SetAdvertisementData(AdvertisementData) returns (Nothing) { option (method_id) = 3; }
 
     // Allowed in link layer states: standby
     // Formatting of scan response data is as per Bluetooth Core Specification.
     // TODO: Include ble spec reference
-    // Maximum scan response length is 13 bytes. Server reserves 18 bytes for streaming service uuids. Scan Response is only possible with scannable advertisements
+    // Maximum scan response length for this method is 13 bytes. Server reserves 18 bytes for streaming service uuids. Scan Response is only possible with scannable advertisements
     // Server will not check validity of the scan response data and only maximum length of each field will be passed to BLE stack
+    // If not set by this method, server will have as scan response data only service uuids.
     rpc SetScanResponseData(AdvertisementData) returns (Nothing) { option (method_id) = 4; }
 
     // Allowed in link layer states: advertising
@@ -235,7 +237,7 @@ service GapPeripheral
     rpc GetAdvertisingAddress(Nothing) returns (Nothing) { option (method_id) = 5; }
 
     // Results in GapPeripheralResponse.IdentityAddress
-    // Identity address is statically configured
+    // Type of the identity address is statically configured
     rpc GetIdentityAddress(Nothing) returns (Nothing) { option (method_id) = 6; }
 
     // Allowed in link layer states: standby
@@ -286,6 +288,7 @@ service GapPeripheralResponse
 
     // TODO: What is the use for these calls?
     // TODO: Do we get these callbacks also when establishing connection from a bonded peer?
+    // TODO: Can we merge these two calls into one with a boolean parameter?
     rpc PairingSuccessfullyCompleted(Nothing) returns(Nothing) { option(method_id) = 5; }
     rpc PairingFailed(PairingStatus) returns(Nothing) { option(method_id) = 6; }
 
@@ -302,6 +305,7 @@ service GapPeripheralReadiness {
     option(service_id) = 36;
 
     // TODO: Clarify when this means: This means GapPeripheral service is ready to be used
+    // TODO: Do we remove this when we merge with Celllar?
     rpc DeviceStarted(Nothing) returns(Nothing) { option(method_id) = 1; }
 }