Bluetooth: Host: Improve bluetooth documentation #87220
Conversation
zephyrbot
added
area: Bluetooth
area: Bluetooth Host
zephyrbot
requested review from
alwa-nordic,
cvinayak,
hermabe,
jhedberg,
rugeGerritsen,
sjanc,
Thalley and
theob-pro
KyraLengfeld
force-pushed
the
improve_bluetooth_docs
branch
3 times, most recently
from
74446e9 to
95b7924
Compare
| * - Acceptance of a new connection | ||
| * - Transmission of scan response data | ||
| * - If PAwR (Periodic Advertising with Response) is enabled: | ||
| * - Expiration of the advertising set's validity |
There was a problem hiding this comment.
This doesnt look correct to me. There are two PAwR related callbacks, pawr_data_request and pawr_response. These are just forwarding the HCI events "LE Periodic Advertising Subevent Data Request event" and "LE Periodic Advertising Response Report event".
There was a problem hiding this comment.
I will take a look, but this specifically is basically paraphrased from the elements of the structure itself (maybe wrongly). Will double check and request your review. Edit: I see now that I slipped in lines while I made that, the Expiration is part of when privacy is enabled not PAwR, will fix.
include/zephyr/bluetooth/bluetooth.h
Outdated
| * @details This struct provides the necessary information to set the data for a specific subevent | ||
| * in a Periodic Advertising with Response (PAwR) scenario. It specifies the subevent number, the | ||
| * range of response slots to listen to, and the actual data to send. This is used to respond to | ||
| * data request from an advertiser by sending back the data in the specified subevent slots. |
There was a problem hiding this comment.
"subevent slots" is a bit unclear. "slots" is generally used for response slots, we can probably just use "subevent" here.
| @@ -1641,7 +1641,7 @@ uint16_t bt_gatt_get_uatt_mtu(struct bt_conn *conn); | |||
|
|
|||
| /** @brief GATT Exchange MTU parameters | |||
| * | |||
| * Used with @ref bt_gatt_exchange_mtu() to initiate an MTU exchange. The | |||
| * Used with @ref bt_gatt_exchange_mtu function to initiate an MTU exchange. The | |||
There was a problem hiding this comment.
In this file you've replace () with @ref when you fixed it.
Should we decide on one approach when referring to functions? It seem we are doing a mix of () and @ref. Doesn't need to be done in this PR though
There was a problem hiding this comment.
@kartben I can't find any doxygen documentation guidelines on https://docs.zephyrproject.org/latest/contribute/documentation/guidelines.html - Should we have any?
There was a problem hiding this comment.
FYI I just removed the () in the gatt.h file, because I added those instances with @ref and () recently myself.
KyraLengfeld
force-pushed
the
improve_bluetooth_docs
branch
from
95b7924 to
7256c00
Compare
This commit imrpoves the bluetooth.h documentation by adding @Briefs and @details to all the structs and enums lacking such, as well as clarifying the existing documentation.