diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0da93bfc..2e99d4d45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -165,4 +165,24 @@ Once unzipped: ## Contributing Documentation -Documentation undergoes the same review process as code and contributions may be mirrored on our [openthread.io](https://openthread.io) website. See the [Documentation Style Guide](https://github.com/openthread/ot-docs/blob/main/STYLE_GUIDE.md) for more information on how to author and format documentation for contribution. +Documentation undergoes the same review process as code and contributions may be mirrored on our [openthread.io](https://openthread.io) website. + +### Codelabs and Guides + +To review and contribute to OpenThread Codelabs and Guides, refer to the following GitHub repositories: + +- [Codelabs](https://github.com/openthread/ot-docs/tree/main/site/en/codelabs) +- [Guides](https://github.com/openthread/ot-docs/tree/main/site/en/guides) + +For information on how to author and format documentation for contribution, refer to the [Documentation Style Guide](https://github.com/openthread/ot-docs/blob/main/STYLE_GUIDE.md). + +### API Reference topics + +API Reference topics use [Doxygen comment blocks](https://www.doxygen.nl/manual/docblocks.html) to render the HTML output on [https://openthread.io/reference](https://openthread.io/reference). OpenThread scripts support the following Doxygen [special commands](https://www.doxygen.nl/manual/commands.html): + +- @file +- @brief +- @param +- @returns + +You can find most of these comments in the [OpenThread header files](https://github.com/openthread/openthread/tree/main/include/openthread). To review an example, refer to [`border_agent.h`](https://github.com/openthread/openthread/tree/main/include/openthread/border_agent.h). The Doxygen comments in `border_agent.h` output the [Border Agent](https://openthread.io/reference/group/api-border-agent) reference topic on openthread.io. For more information, refer to [Comments](https://github.com/openthread/openthread/blob/main/STYLE_GUIDE.md#comments) in the OpenThread Coding Conventions and Style guide. diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 0feed0524..d8ea62496 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -176,6 +176,14 @@ - Describes the purpose, function, and influence of each parameter as well as whether it is an input, an output, or both. - Describes the return value, if present, and the expected range or constraints of it. +If your description is longer than 120 characters, continue the comment on the next line: + +``` + * @brief + * Records the history of different events, for example RX and TX messages or network info changes. All tracked + * entries are timestamped. +``` + # Python ## Standards diff --git a/doc/ot_api_doc.h b/doc/ot_api_doc.h index 203feb1cb..8843171e6 100644 --- a/doc/ot_api_doc.h +++ b/doc/ot_api_doc.h @@ -120,13 +120,13 @@ * @} * * @defgroup api-cli Command Line Interface - * @defgroup api-crypto Crypto + * @defgroup api-crypto Crypto - Thread Stack * @defgroup api-entropy Entropy Source - * @defgroup api-factory-diagnostics Factory Diagnostics + * @defgroup api-factory-diagnostics Factory Diagnostics - Thread Stack * @defgroup api-heap Heap * @defgroup api-history-tracker History Tracker * @defgroup api-jam-detection Jam Detection - * @defgroup api-logging Logging + * @defgroup api-logging Logging - Thread Stack * @defgroup api-ncp Network Co-Processor * @defgroup api-network-time Network Time Synchronization * @defgroup api-random-group Random Number Generator @@ -154,9 +154,10 @@ * @{ * * @defgroup plat-alarm Alarm + * @defgroup plat-crypto Crypto - Platform * @defgroup plat-entropy Entropy - * @defgroup plat-factory-diagnostics Factory Diagnostics - * @defgroup plat-logging Logging + * @defgroup plat-factory-diagnostics Factory Diagnostics - Platform + * @defgroup plat-logging Logging - Platform * @defgroup plat-memory Memory * @defgroup plat-messagepool Message Pool * @defgroup plat-misc Miscellaneous diff --git a/include/openthread/history_tracker.h b/include/openthread/history_tracker.h index 0cce3e75e..4f496d161 100644 --- a/include/openthread/history_tracker.h +++ b/include/openthread/history_tracker.h @@ -38,18 +38,13 @@ extern "C" { /** * @addtogroup api-history-tracker * - * @{ - * - */ - -/** * @brief - * This header defines the public API for History Tracker. + * Records the history of different events, for example RX and TX messages or network info changes. All tracked + * entries are timestamped. * - * History Tracker module records history of different events (e.g. RX and TX messages or network info changes, etc.) - * as the Thread network operates. All tracked entries are timestamped. + * The functions in this module are available when `OPENTHREAD_CONFIG_HISTOR_TRACKER_ENABLE` is enabled. * - * The functions in this module are available when `OPENTHREAD_CONFIG_HISTOR_TRACKER_ENABLE` is enabled. + * @{ * */ diff --git a/include/openthread/instance.h b/include/openthread/instance.h index c9ed005b9..28eb327f1 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -53,7 +53,7 @@ extern "C" { * @note This number versions both OpenThread platform and user APIs. * */ -#define OPENTHREAD_API_VERSION (177) +#define OPENTHREAD_API_VERSION (178) /** * @addtogroup api-instance diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h index 318ed9d16..2d7a654b9 100644 --- a/include/openthread/platform/radio.h +++ b/include/openthread/platform/radio.h @@ -57,7 +57,7 @@ extern "C" { */ /** - * @defgroup radio-types Types + * @defgroup radio-types Radio Types * * @brief * This module includes the platform abstraction for a radio frame. @@ -399,7 +399,7 @@ typedef struct otLinkMetrics */ /** - * @defgroup radio-config Configuration + * @defgroup radio-config Radio Configuration * * @brief * This module includes the platform abstraction for radio configuration. @@ -643,7 +643,7 @@ uint32_t otPlatRadioGetBusSpeed(otInstance *aInstance); */ /** - * @defgroup radio-operation Operation + * @defgroup radio-operation Radio Operation * * @brief * This module includes the platform abstraction for radio operations.