[PATCH] clk: add missing function short descriptions for kernel-doc

[PATCH] clk: add missing function short descriptions for kernel-doc

[Randy Dunlap]

Add short descriptions for 3 functions which are missing it.
Modify the parameter name in comments to be @core instead of clk.
Use corrected function names (with leading "__") in a few places.

Warning: drivers/clk/clk.c:1899 missing initial short description on line:
 * __clk_recalc_accuracies
Warning: drivers/clk/clk.c:1972 missing initial short description on line:
 * __clk_recalc_rates
Warning: drivers/clk/clk.c:2244 missing initial short description on line:
 * __clk_speculate_rates

This eliminates warnings in this file except for missing return value
warnings, of which there are around 70.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Brian Masney <bmasney@redhat.com>
Cc: Michael Turquette <mturquette@baylibre.com>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-clk@vger.kernel.org

 drivers/clk/clk.c |   16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

--- linux-next-20260508.orig/drivers/clk/clk.c
+++ linux-next-20260508/drivers/clk/clk.c
@@ -1846,10 +1846,10 @@ static int __clk_notify(struct clk_core
 }
 
 /**
- * __clk_recalc_accuracies
+ * __clk_recalc_accuracies - recalculate all accuracies in the clk subtree
  * @core: first clk in the subtree
  *
- * Walks the subtree of clks starting with clk and recalculates accuracies as
+ * Walks the subtree of clks starting with @core and recalculates accuracies as
  * it goes.  Note that if a clk does not implement the .recalc_accuracy
  * callback then it is assumed that the clock will take on the accuracy of its
  * parent.
@@ -1919,16 +1919,16 @@ static unsigned long clk_recalc(struct c
 }
 
 /**
- * __clk_recalc_rates
+ * __clk_recalc_rates - recalculate all rates in the clk subtree
  * @core: first clk in the subtree
  * @update_req: Whether req_rate should be updated with the new rate
  * @msg: notification type (see include/linux/clk.h)
  *
- * Walks the subtree of clks starting with clk and recalculates rates as it
+ * Walks the subtree of clks starting with @core and recalculates rates as it
  * goes.  Note that if a clk does not implement the .recalc_rate callback then
  * it is assumed that the clock will take on the rate of its parent.
  *
- * clk_recalc_rates also propagates the POST_RATE_CHANGE notification,
+ * __clk_recalc_rates also propagates the POST_RATE_CHANGE notification,
  * if necessary.
  */
 static void __clk_recalc_rates(struct clk_core *core, bool update_req,
@@ -2191,14 +2191,14 @@ static int __clk_set_parent(struct clk_c
 }
 
 /**
- * __clk_speculate_rates
+ * __clk_speculate_rates - speculate all rates in the clk subtree
  * @core: first clk in the subtree
  * @parent_rate: the "future" rate of clk's parent
  *
- * Walks the subtree of clks starting with clk, speculating rates as it
+ * Walks the subtree of clks starting with @core, speculating rates as it
  * goes and firing off PRE_RATE_CHANGE notifications as necessary.
  *
- * Unlike clk_recalc_rates, clk_speculate_rates exists only for sending
+ * Unlike __clk_recalc_rates, __clk_speculate_rates exists only for sending
  * pre-rate change notifications and returns early if no clks in the
  * subtree have subscribed to the notifications.  Note that if a clk does not
  * implement the .recalc_rate callback then it is assumed that the clock will

Re: [PATCH] clk: add missing function short descriptions for kernel-doc

[Brian Masney]

On Tue, May 12, 2026 at 02:24:53PM -0700, Randy Dunlap wrote:
> Add short descriptions for 3 functions which are missing it.
> Modify the parameter name in comments to be @core instead of clk.
> Use corrected function names (with leading "__") in a few places.
> 
> Warning: drivers/clk/clk.c:1899 missing initial short description on line:
>  * __clk_recalc_accuracies
> Warning: drivers/clk/clk.c:1972 missing initial short description on line:
>  * __clk_recalc_rates
> Warning: drivers/clk/clk.c:2244 missing initial short description on line:
>  * __clk_speculate_rates
> 
> This eliminates warnings in this file except for missing return value
> warnings, of which there are around 70.
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

Reviewed-by: Brian Masney <bmasney@redhat.com>