Bluetooth: Host: improve GATT documentation #86359
Conversation
zephyrbot
added
area: Bluetooth
area: Bluetooth Host
zephyrbot
requested review from
alwa-nordic,
cvinayak,
hermabe,
jhedberg,
rugeGerritsen,
sjanc,
Thalley and
theob-pro
KyraLengfeld
added
the
Trivial
|
Great! Will do a proper review once it passes CI. Did you use https://docs.zephyrproject.org/api-coverage/latest/zephyr/bluetooth/gatt.h.gcov.html to find the missing parts? |
The gatt docs are very sparce, this commit adds imrpovements for the GATT server API part. Others will follow. Signed-off-by: Kyra Lengfeld <[email protected]>
KyraLengfeld
force-pushed
the
improve_gatt_docs
branch
from
80ba50d to
6df1842
Compare
Nope :) but we should probably use that once all our planned additions are in to double check. (We tried splitting our planned doc improvements into trivial chunks. So there will be a handful more small PRs coming anyway.) |
| @@ -645,7 +648,7 @@ typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr, | |||
| * Iterate attributes in the given range matching given UUID and/or data. | |||
| * | |||
| * @param start_handle Start handle. | |||
| * @param end_handle End handle. | |||
| * @param end_handle End handle. Often set to start_handle + attr_count or 0xFFFF. | |||
There was a problem hiding this comment.
We could consider referring to BT_ATT_LAST_ATTRIBUTE_HANDLE instead of 0xFFFF
| /** | ||
| * @brief Gatt Characterisitc Initialization Macro. |
There was a problem hiding this comment.
The style in this file seems to be to have @brief on the same line as /**
| * \internal | ||
| * @note Only use this with attributes which user_data is a _bt_gatt_ccc. | ||
| * _bt_gatt_ccc being the internal representation of CCC value. | ||
| * \endinternal |
There was a problem hiding this comment.
AFAIK the way to make things internal is to use @cond INTERNAL_HIDDEN + @endcond. @kartben please verify
| * See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter. | ||
| * | ||
| */ |
There was a problem hiding this comment.
| * See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter. | |
| * | |
| */ | |
| * See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter. | |
| */ |
| #if defined(CONFIG_BT_EATT) | ||
| /** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */ | ||
| enum bt_att_chan_opt chan_opt; | ||
| #endif /* CONFIG_BT_EATT */ |
There was a problem hiding this comment.
Maybe outside the scope of this PR, but AFAIk we need to do something like
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
to ensure that they are in the Doxygen documentation when they are otherwise guarded. @kartben please verify
The gatt docs are very sparce, this commit adds imrpovements for the GATT server API part. Others will follow.