doc: ieee802154: improved documentation structure, OT cross-reference and documentation details #62503
Conversation
which ones? |
@kartben Oups, I dreamed that. I just wanted to make screenshots for you when I realized that I was confusing enums and defines which had almost the same name. Sorry. Looks like this is ready for a quick preliminary review then if you find the time. |
ghost
self-assigned this
ghost
added
area: OpenThread
area: IEEE 802.15.4
area: Documentation
DNM
ghost
mentioned this pull request
ghost
mentioned this pull request
Fixes bugs in USB and DSA group titles (networking) and a minor bug in sys/utils. Signed-off-by: Florian Grandel <[email protected]>
Improves the API documentation including it's structure and integration into the Zephyr documentation. Previously the API status of the IEEE 802.15.4 API (and its sub-APIs) was unclear. This change adds three APIs in an "unstable" state: - IEEE 802.15.4 L2 for subsystem developers - IEEE 802.15.4 drivers for driver developers - IEEE 802.15.4 net_mgmt for application developers The corresponding APIs are documented at a group level. These sub-APIs need to be separately versioned as they have different audiences, change velocities and levels of stability. Signed-off-by: Florian Grandel <[email protected]>
Integrates and cross-references OpenThread and native IEEE 802.15.4 docs as they share a common driver layer. While OpenThread is of course not an IEEE 802.15.4 subsystem API it is still included in the ieee802154 documentation group, purely for convenience to the documentation readers. For organizational purposes OT is considered a separate area of maintenance and therefore keeps its dedicated documentation page - but the two subsystems now cross-reference each other for convenience. Signed-off-by: Florian Grandel <[email protected]>
Hides types used in the IEEE 802.15.4 L2 sub-API and L2-internal APIs that are of no public interest and improves documentation of the remainder. The changes are mostly minor as the API documentation had already been improved and clarified in previous changes. Also includes non-visible documentation to the subsystem-internal Frame API by adding references to the specification. Signed-off-by: Florian Grandel <[email protected]>
Hides types in the IEEE 802.15.4 driver sub-API that are of no public interest and improves documentation of the remainder. Apart from extending and clarifying many details of the driver API, this change also specifies certain formal properties of API calls, such as "sleeps" or "isr-ok". Plus it removes semantic ambivalence that had been resolved and hidden in existing implementation details but is highly relevant to the way the API can be used and shall be implemented. As far as possible this change introduces formal requirements language (MAY, SHALL/MUST, SHOULD) to specify driver implementation requirements. This change also introduces two definitions - for the moment being of purely documentary relevance (i.e. to be referred in the documentation): * IEEE802154_CONFIG_RX_SLOT_NONE * IEEE802154_CONFIG_RX_SLOT_OFF These "magic" values are required to clarify the exact semantics of RX slots as to receiver activity. Signed-off-by: Florian Grandel <[email protected]>
Hides types in the IEEE 802.15.4 net_mgmt sub-API that are of no public interest and improves documentation of the remainder. All constants that are not meant to be used by applications have been hidden. Only the API actually being of relevance to application developers is now publicly visible and documented. Signed-off-by: Florian Grandel <[email protected]>
ghost
marked this pull request as ready for review
ghost
requested review from
carlescufi,
jukkar,
nashif and
tbursztyka
as code owners
|
@kartben @carlescufi Open for review now - proposes IEEE 802.15.4 as "unstable" and divided up as discussed. @rlubos No changes introduced since your last review (except for improved commit messages and a few lines of extra docs for members that had none yet - I ensured that the compare button works for you by pushing the rebase separately). Needs re-approval, though, as I removed the draft status and rebased. @jukkar Would be nice to hear your opinion as well re the proposal to split up into three sub-APIs and mark them as "unstable" for now. |
carlescufi
left a comment
carlescufi
left a comment
There was a problem hiding this comment.
OK for the API maturity level changes
6 participants
This PR intends to improve the overall IEEE 802.15.4 documentation and resolve ambivalence re it's stability:
Currently all L2/L1s seem to be subsumed under "network" but IMO that doesn't make sense as it does not allow us to address the different versioning requirements of IEEE 802.15.4 sub-APIs nor does it allow us to differentiate the stability of Ethernet, Bluetooth, CAN and IEEE 802.15.4.
This PR therefore proposes to version the IEEE 802.15.4 subsystem at three independent levels (all of which I consider UNSTABLE for now):
This allows us to address the different requirements of the three sub-APIs re versioning and change management:
For all practical purposes, @rlubos, @jukkar and I considered the existing user base of those APIs small and the changes required for its transformation many so that we agreed to treat it de facto as unstable over the last three releases (which I'm proposing to formalize now).
This strategy seems to have worked out well. AFAICS we didn't get a single complaint and a lot of positive feedback for that approach from the community.