Merge pull request #14820 from paul-szczepanek-arm/events-doc

BLE: Clarify ble event docs with crossreferences

Author: 0xc0170

connectivity/FEATURE_BLE/include/ble/Gap.h

@@ -302,7 +302,7 @@ class Gap {
      */
     struct EventHandler {
         /**
-         * Called when an advertising device receive a scan response.
+         * Called when an advertising device receive a scan request.
          *
          * @param event Scan request event.
          *
@@ -319,6 +319,8 @@ class Gap {
          *
          * @param event Advertising start event.
          *
+         * @note Check event.getStatus() to see if advertising started successfully
+         *
          * @see startAdvertising()
          */
         virtual void onAdvertisingStart(const AdvertisingStartEvent &event)
@@ -333,7 +335,8 @@ class Gap {
          *
          * @param event Advertising end event.
          *
-         * @see startAdvertising()
+         * @note Check event.getStatus() to see if advertising ended successfully
+         *
          * @see stopAdvertising()
          * @see onConnectionComplete()
          */
@@ -409,8 +412,9 @@ class Gap {
         }
 
         /**
-         * Called when connection attempt ends or an advertising device has been
-         * connected.
+         * Called when connection attempt ends. Check event.getStatus() to see if connection
+         * was established. If this device is the peripheral and it was advertising this will
+         * end the advertising set which will also create the onAdvertisingEnd event.
          *
          * @see startAdvertising()
          * @see connect()
@@ -431,8 +435,8 @@ class Gap {
          *
          * @version 4.1+.
          *
-         * @note This event is not generated if connection parameters update
-         * is managed by the middleware.
+         * @note This event will only be produced if manageConnectionParametersUpdateRequest() was called
+         * with true. Otherwise the stack will handle the request and no event will be generated.
          *
          * @see manageConnectionParametersUpdateRequest()
          * @see acceptConnectionParametersUpdate()
@@ -553,6 +557,8 @@ class Gap {
         /**
          * Function invoked when the privacy subsystem has been enabled and is
          * ready to be used.
+         *
+         * @see enablePrivacy()
          */
         virtual void onPrivacyEnabled()
         {
@@ -1087,6 +1093,7 @@ class Gap {
      * @see EventHandler::onUpdateConnectionParametersRequest when a central
      * receives a request to update the connection parameters.
      *
+     * @see onUpdateConnectionParametersRequest
      * @see acceptConnectionParametersUpdate to accept the request.
      * @see rejectConnectionParametersUpdate to reject the request.
      */
@@ -1286,6 +1293,8 @@ class Gap {
      * false to disable it.
      *
      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
+     *
+     * @see EventHandler::onPrivacyEnabled()
      */
     ble_error_t enablePrivacy(bool enable);
 
@@ -1433,7 +1442,7 @@ class Gap {
      */
     ble_error_t reset();
 
-        /**
+    /**
      * Register a Gap shutdown event handler.
      *
      * The handler is called when the Gap instance is about to shut down.

connectivity/FEATURE_BLE/include/ble/GattClient.h

@@ -107,6 +107,8 @@ class GattClient {
          *
          * @param connectionHandle The handle of the connection that changed the size.
          * @param attMtuSize
+         *
+         * @see negotiateAttMtu()
          */
         virtual void onAttMtuChange(
             ble::connection_handle_t connectionHandle,

connectivity/FEATURE_BLE/include/ble/GattServer.h

@@ -112,6 +112,8 @@ class GattServer {
          *
          * @param connectionHandle The handle of the connection that changed the size.
          * @param attMtuSize
+         *
+         * @see negotiateAttMtu()
          */
         virtual void onAttMtuChange(
             ble::connection_handle_t connectionHandle,
@@ -162,14 +164,14 @@ class GattServer {
 
         /**
          * Function invoked when the GattServer instance is about
-         * to be shut down. This can result in a call to reset() or BLE::reset().
+         * to be shut down. This can be the result of a call to reset() or BLE::reset().
          */
         virtual void onShutdown(const GattServer &server) {
             (void)server;
         }
 
         /**
-         * Function invoked when the client has subscribed to characteristic updates
+         * Function invoked when the client has subscribed to characteristic updates.
          *
          * @note params has a temporary scope and should be copied by the
          * application if needed later
@@ -179,7 +181,7 @@ class GattServer {
         }
 
         /**
-         * Function invoked when the client has unsubscribed to characteristic updates
+         * Function invoked when the client has unsubscribed from characteristic updates.
          *
          * @note params has a temporary scope and should be copied by the
          * application if needed later
@@ -303,9 +305,11 @@ class GattServer {
      * GattServer state.
      *
      * @note This function is meant to be overridden in the platform-specific
-     * subclass. Overides must call the parent function before any cleanup.
+     * subclass. Overrides must call the parent function before any cleanup.
      *
      * @return BLE_ERROR_NONE on success.
+     *
+     * @see EventHandler::onShutdown()
      */
     ble_error_t reset();
 
@@ -401,6 +405,9 @@ class GattServer {
      *
      * @return BLE_ERROR_NONE if the attribute value has been successfully
      * updated.
+     *
+     * @see EventHandler::onDataSent(), this will only be triggered if there are
+     * client subscribed and the localOnly parameter is set to false.
      */
     ble_error_t write(
         GattAttribute::Handle_t attributeHandle,
@@ -429,6 +436,9 @@ class GattServer {
      *
      * @return BLE_ERROR_NONE if the attribute value has been successfully
      * updated.
+     *
+     * @see EventHandler::onDataSent(), this will only be triggered if there are
+     * client subscribed and the localOnly parameter is set to false.
      */
     ble_error_t write(
         ble::connection_handle_t connectionHandle,
@@ -448,6 +458,8 @@ class GattServer {
      *
      * @return BLE_ERROR_NONE if the connection and handle are found. False
      * otherwise.
+     *
+     * @see EventHandler::onDataSent()
      */
     ble_error_t areUpdatesEnabled(
         const GattCharacteristic &characteristic,
@@ -466,6 +478,8 @@ class GattServer {
      *
      * @return BLE_ERROR_NONE if the connection and handle are found. False
      * otherwise.
+     *
+     * @see EventHandler::onDataSent()
      */
     ble_error_t areUpdatesEnabled(
         ble::connection_handle_t connectionHandle,