Bluetooth: ISO: Fix and format iso.h documentation #75376
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
zephyrbot
requested review from
asbjornsabo,
hermabe,
jhedberg,
sjanc and
Vudentz
kruithofa
requested changes
Jul 5, 2024
include/zephyr/bluetooth/iso.h
Outdated
| @@ -172,77 +174,82 @@ struct bt_iso_chan { | |||
| */ | |||
| bt_security_t required_sec_level; | |||
| #endif /* CONFIG_BT_SMP && CONFIG_BT_ISO_UNICAST */ | |||
| /** Node used internally by the stack */ | |||
| /** @internal Node used internally by the stack */ | |||
| sys_snode_t node; | |||
| }; | |||
|
|
|||
| /** @brief ISO Channel IO QoS structure. */ | |||
| struct bt_iso_chan_io_qos { | |||
| /** Channel SDU. Maximum value is BT_ISO_MAX_SDU */ | |||
There was a problem hiding this comment.
Suggested change
| /** Channel SDU. Maximum value is BT_ISO_MAX_SDU */ | |
| /** | |
| * @brief Channel SDU. | |
| * | |
| * Channel SDU, maximum value is @ref BT_ISO_MAX_SDU | |
| */ |
| @@ -271,7 +278,8 @@ enum { | |||
| /** The ISO packet is valid. */ | |||
| BT_ISO_FLAGS_VALID = BIT(0), | |||
|
|
|||
| /** @brief The ISO packet may possibly contain errors. | |||
| /** | |||
There was a problem hiding this comment.
Shouldn't we also document the BT_ISO_FLAGS_VALID and BT_ISO_FLAGS_LOST?
There was a problem hiding this comment.
The purpose of this PR was not to re-write existing documentation, and they are technically, however poorly, documented.
| * | ||
| * BT_ISO_FRAMING_UNFRAMED for unframed and | ||
| * BT_ISO_FRAMING_FRAMED for framed. | ||
| * @ref BT_ISO_FRAMING_UNFRAMED for unframed and @ref BT_ISO_FRAMING_FRAMED for framed. | ||
| */ | ||
| uint8_t framing; | ||
|
|
||
| /** Whether or not to encrypt the streams. */ |
There was a problem hiding this comment.
Suggested change
| /** Whether or not to encrypt the streams. */ | |
| /** @brief Whether or not to encrypt the streams. */ |
There was a problem hiding this comment.
Not necessary. @brief is implied, and is generally not not used when there is only a single line
| * | ||
| * Value range is BT_ISO_SYNC_TIMEOUT_MIN to BT_ISO_SYNC_TIMEOUT_MAX. | ||
| * Value range is @ref BT_ISO_SYNC_TIMEOUT_MIN to @ref BT_ISO_SYNC_TIMEOUT_MAX. | ||
| */ | ||
| uint16_t sync_timeout; | ||
|
|
||
| /** Whether or not the streams of the BIG are encrypted */ |
There was a problem hiding this comment.
Suggested change
| /** Whether or not the streams of the BIG are encrypted */ | |
| /** @brief Whether or not the streams of the BIG are encrypted */ |
| @@ -674,13 +702,15 @@ struct bt_iso_accept_info { | |||
| /** The ACL connection that is requesting authorization */ | |||
There was a problem hiding this comment.
Suggested change
| /** The ACL connection that is requesting authorization */ | |
| /** @brief The ACL connection that is requesting authorization */ |
| @@ -513,52 +534,55 @@ struct bt_iso_big_sync_param { | |||
| /** Array of pointers to BIS channels */ | |||
There was a problem hiding this comment.
Suggested change
| /** Array of pointers to BIS channels */ | |
| /** @brief Array of pointers to BIS channels */ |
Thalley
force-pushed
the
iso_doc_updates
branch
2 times, most recently
from
d2216e3
to
561bb95
Compare
|
@kruithofa please re-review |
kruithofa
previously approved these changes
Jul 9, 2024
niym-ot
previously approved these changes
Jul 10, 2024
theob-pro
reviewed
Jul 10, 2024
niym-ot
previously approved these changes
Jul 10, 2024
Fixed a few bad or missing documentation parts of iso.h Also formatted some parts to be consistent with not just the file itself, but also with bluetooth.h Signed-off-by: Emil Gydesen <[email protected]>
theob-pro
approved these changes
Jul 10, 2024
alwa-nordic
approved these changes
Jul 10, 2024
jhedberg
approved these changes
Jul 10, 2024
kruithofa
approved these changes
Jul 10, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixed a few bad or missing documentation parts of iso.h Also formatted some parts to be consistent with not just the file itself, but also with bluetooth.h