diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h
index dd834fbbec..ab55037e0e 100644
--- a/features/FEATURE_BLE/ble/Gap.h
+++ b/features/FEATURE_BLE/ble/Gap.h
@@ -299,6 +299,21 @@ class GapAdvertisingData;
  * controller/stack. To catch all disconnection events, application code may
  * set up an handler taking care of disconnection events by calling
  * onDisconnection().
+ *
+ * * @par Modulation Schemes
+ *
+ * When supported by the host and controller you can select modulation schemes
+ * from available ones
+ * (@see BLUETOOTH SPECIFICATION Version 5.0 | Vol 1, Part A - 1.2). You may set
+ * preferred PHY, separately for RX and TX using setPreferredPhys(). You may also
+ * set the currently used PHY on a selected connection using setPhy(). Both of these
+ * are however only advisory and the controller is allowed to make its own decision
+ * on the best PHY to use based on your request, the peer's supported features and
+ * physical conditions. You may query the currently used PHY using readPhy() which
+ * will return the result through a call to the registered Gap::EventHandler.
+ * You may register the event handler with setEventHandler(). The events inform
+ * about the currently used PHY and of any changes to PHY which may be triggered
+ * autonomously byt the controller or by the peer.
  */
 class Gap {
     /*