clarify documentation for adv stop event

Author: paul-szczepanek-arm

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,

connectivity/FEATURE_BLE/source/pal/PalGap.h

@@ -193,9 +193,9 @@ struct PalGapEventHandler {
 
     /** 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(