From c4585b977df2fc17ad20f282f48298bed7d3de06 Mon Sep 17 00:00:00 2001
From: Paul Szczepanek <paul.szczepanek@arm.com>
Date: Wed, 9 Jun 2021 13:56:39 +0100
Subject: [PATCH] clarify documentation for adv stop event

---
 connectivity/FEATURE_BLE/include/ble/gap/Events.h | 11 ++++++++---
 connectivity/FEATURE_BLE/source/pal/PalGap.h      |  4 ++--
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/connectivity/FEATURE_BLE/include/ble/gap/Events.h b/connectivity/FEATURE_BLE/include/ble/gap/Events.h
index a676ba14d6..7d269af836 100644
--- a/connectivity/FEATURE_BLE/include/ble/gap/Events.h
+++ b/connectivity/FEATURE_BLE/include/ble/gap/Events.h
@@ -627,10 +627,15 @@ struct AdvertisingEndEvent {
     /** Create an extended advertising end event.
      *
      * @param advHandle Advertising set handle.
-     * @param connection Connection handle.
-     * @param completed_events Number of events created during before advertising end.
+     * @param connection Connection handle - only valid if connected is True.
+     * @param completed_events Number of events created during before advertising end - only valid
+     *        if advertising end has been caused by BLE_ERROR_LIMIT_REACHED, not the local user.
+     *        Check getStatus().
      * @param connected True if connection has been established.
-     * @param status Error code if stop command failed.
+     * @param status Error code showing the reason for event. BLE_ERROR_LIMIT_REACHED if set number
+     *        of events have been reached. BLE_ERROR_TIMEOUT if set time has elapsed.
+     *        BLE_ERROR_SUCCESS if connection occurred or user ended the set. Check isConnected()
+     *        to determine which.
      */
     AdvertisingEndEvent(
         advertising_handle_t advHandle,
diff --git a/connectivity/FEATURE_BLE/source/pal/PalGap.h b/connectivity/FEATURE_BLE/source/pal/PalGap.h
index f3dacc496d..41f3da1fcb 100644
--- a/connectivity/FEATURE_BLE/source/pal/PalGap.h
+++ b/connectivity/FEATURE_BLE/source/pal/PalGap.h
@@ -193,9 +193,9 @@ public:
 
     /** Called when advertising set stops advertising.
      *
-     * @param status SUCCESS if connection has been established.
+     * @param status SUCCESS if connection has been established or if stopped by user.
      * @param advertising_handle Advertising set handle.
-     * @param advertising_handle Connection handle.
+     * @param advertising_handle Connection handle. Set to invalid handle if no connection made.
      * @param number_of_completed_extended_advertising_events Number of events created during before advertising end.
      */
     virtual void on_advertising_set_terminated(