[doxygen] add doxygen comment for clk.c and clk.h (#9950)

Accroding to #9947 and #9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations.
    - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies.
    - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify.
    - clk_release implements may be incomplete, so I just marked in comment.

Signed-off-by: 1078249029 <[email protected]>

1 files changed, 44 insertions, 18 deletions

diff --git a/components/drivers/include/drivers/clk.h b/components/drivers/include/drivers/clk.h
index 97491bf8be..9ecf4c3bdf 100644
--- a/components/drivers/include/drivers/clk.h
+++ b/components/drivers/include/drivers/clk.h
@@ -1,11 +1,12 @@
 /*
- * Copyright (c) 2006-2022, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2022-11-26     GuEe-GUI     first version
+ * 2025-01-24     wumingzi     add doxygen comment
  */
 
 #ifndef __CLK_H__
@@ -16,29 +17,40 @@
 #include <ref.h>
 #include <drivers/ofw.h>
 
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    clk              clk
+ * @brief       clk driver api
+ * @ingroup     Drivers
+ * @addtogroup  clk
+ * @{
+ */
+
 #define RT_CLK_NODE_OBJ_NAME    "CLKNP"
 
 struct rt_clk_ops;
 struct rt_reset_control_node;
 
+/**
+ * @brief  Clk node, it is a pat of clk source or controller
+ * @note   Defined as the array like this if the CLK have multi out clocks:
+ * @code{.c}
+ *       struct XYZ_single_clk
+ *       {
+ *           struct rt_clk_node parent;
+ *           ...
+ *       };
+ *
+ *       struct XYZ_multi_clk
+ *       {
+ *           struct rt_clk_node parent[N];
+ *           ...
+ *       };
+ * @endcode
+ *          We assume the 'N' is the max value of element in 'clock-indices' if OFW.
+ */
 struct rt_clk_node
 {
-    /*
-     * Defined as the array like this if if the CLK have multi out clocks:
-     *
-     *  struct XYZ_single_clk
-     *  {
-     *      struct rt_clk_node parent;
-     *      ...
-     *  };
-     *
-     *  struct XYZ_multi_clk
-     *  {
-     *      struct rt_clk_node parent[N];
-     *      ...
-     *  };
-     * We assume the 'N' is the max value of element in 'clock-indices' if OFW.
-     */
     struct rt_object rt_parent;
 
     rt_list_t list;
@@ -62,6 +74,9 @@ struct rt_clk_node
     rt_size_t multi_clk;
 };
 
+/**
+ * @brief   Constant rate clk
+ */
 struct rt_clk_fixed_rate
 {
     struct rt_clk_node clk;
@@ -70,6 +85,9 @@ struct rt_clk_fixed_rate
     rt_ubase_t fixed_accuracy;
 };
 
+/**
+ * @brief   Clk object, it can be clk source or controller
+ */
 struct rt_clk
 {
     struct rt_clk_node *clk_np;
@@ -85,6 +103,9 @@ struct rt_clk
     void *priv;
 };
 
+/**
+ * @brief   Clk array
+ */
 struct rt_clk_array
 {
     rt_size_t count;
@@ -118,6 +139,9 @@ struct rt_clk_notifier;
 typedef rt_err_t (*rt_clk_notifier_callback)(struct rt_clk_notifier *notifier,
         rt_ubase_t msg, rt_ubase_t old_rate, rt_ubase_t new_rate);
 
+/**
+ * @brief   Clock notifier, it containers of clock list and callback function
+ */
 struct rt_clk_notifier
 {
     rt_list_t list;
@@ -192,4 +216,6 @@ rt_inline rt_ssize_t rt_ofw_count_of_clk(struct rt_ofw_node *clk_ofw_np)
 }
 #endif /* RT_USING_OFW */
 
-#endif /* __CLK_H__ */
+/*! @}*/
+
+#endif /* __CLK_H__ */
\ No newline at end of file