[documentation] update code comments and contributing section (#7240)

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.

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

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

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.
+ * @{
  *
  */
 

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

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.