Skip to content

BLE: Clarify ble event docs with crossreferences #14820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 1, 2021
Merged

BLE: Clarify ble event docs with crossreferences #14820

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
55657c5
clarify ble event docs with corssreferences
paul-szczepanek-arm Jun 23, 2021
25211f5
missing cross refernces and grammar
paul-szczepanek-arm Jun 28, 2021
1ba5b25
fix calls with params in docs so they are referenced correclty
paul-szczepanek-arm Jun 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions connectivity/FEATURE_BLE/include/ble/Gap.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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)
Expand All @@ -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()
*/
Expand Down Expand Up @@ -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 as advertising this will
* end advertising which will also create the onAdvertisingEnd event.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Called when connection attempt ends. Check event.getStatus() to see if connection
* was established. If this device is the peripheral and it as advertising this will
* end advertising which will also create the onAdvertisingEnd event.
* 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()
Expand All @@ -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(true)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

manageConnectionParametersUpdateRequest(true) won't be cross referenced

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you address this ? I think This event will only be produced if manageConnectionParametersUpdateRequest() was called with true. would work. What do you think ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I misundestood, I though you meant the doc for manageConnectionParametersUpdateRequest isn't cross refed, so I added the @see over there.

* was called. Otherwise the stack will handle the request and no event will be generated.
*
* @see manageConnectionParametersUpdateRequest()
* @see acceptConnectionParametersUpdate()
Expand Down Expand Up @@ -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()
{
Expand Down Expand Up @@ -1286,6 +1292,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);

Expand Down Expand Up @@ -1433,7 +1441,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.
Expand Down
2 changes: 2 additions & 0 deletions connectivity/FEATURE_BLE/include/ble/GattClient.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
22 changes: 18 additions & 4 deletions connectivity/FEATURE_BLE/include/ble/GattServer.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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();

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down
Loading