[PATCH v2] interconnect: Add kernel-doc for devm_of_icc_get(), icc_enable() and icc_disable()

[PATCH v2] interconnect: Add kernel-doc for devm_of_icc_get(), icc_enable() and icc_disable()

[Karl Mehltretter]

Documentation/driver-api/interconnect.rst lists devm_of_icc_get(),
icc_enable() and icc_disable() in its kernel-doc directive for
drivers/interconnect/core.c, but none of the three functions has a
kernel-doc comment. The directive silently produces nothing for them, so
the consumer API section of the rendered documentation never shows
them.

Add kernel-doc comments in the style of the neighbouring functions.

Assisted-by: LLM
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
Changes in v2:
- Describe @path as an interconnect path and explicitly state that
  passing NULL is a no-op returning 0 for both icc_enable() and
  icc_disable() (Kuan-Wei Chiu).

v1: https://lore.kernel.org/r/20260907020504.24783-1-kmehltretter@gmail.com/

 drivers/interconnect/core.c | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/drivers/interconnect/core.c b/drivers/interconnect/core.c
index 4aa991a54101..802f07e806d5 100644
--- a/drivers/interconnect/core.c
+++ b/drivers/interconnect/core.c
@@ -423,6 +423,17 @@ static void devm_icc_release(struct device *dev, void *res)
 	icc_put(*(struct icc_path **)res);
 }
 
+/**
+ * devm_of_icc_get() - get a path handle from a DT node based on name
+ * @dev: device pointer for the consumer device
+ * @name: interconnect path name
+ *
+ * This function is the resource managed version of of_icc_get(). The path
+ * is released with icc_put() automatically when @dev is unbound.
+ *
+ * Return: icc_path pointer on success or ERR_PTR() on error. NULL is returned
+ * when the API is disabled or the "interconnects" DT property is missing.
+ */
 struct icc_path *devm_of_icc_get(struct device *dev, const char *name)
 {
 	struct icc_path **ptr, *path;
@@ -786,12 +797,33 @@ static int __icc_enable(struct icc_path *path, bool enable)
 			  path->reqs[0].peak_bw);
 }
 
+/**
+ * icc_enable() - enable a path
+ * @path: interconnect path
+ *
+ * Mark all requests on the path as enabled and reapply the bandwidth that
+ * was last set with icc_set_bw().
+ * Passing a NULL @path is a no-op and returns 0.
+ *
+ * Return: 0 on success, or an appropriate error code otherwise.
+ */
 int icc_enable(struct icc_path *path)
 {
 	return __icc_enable(path, true);
 }
 EXPORT_SYMBOL_GPL(icc_enable);
 
+/**
+ * icc_disable() - disable a path
+ * @path: interconnect path
+ *
+ * Mark all requests on the path as disabled, so that they no longer count
+ * towards the aggregated bandwidth, and reapply the constraints. The
+ * requested bandwidth is kept and restored by icc_enable().
+ * Passing a NULL @path is a no-op and returns 0.
+ *
+ * Return: 0 on success, or an appropriate error code otherwise.
+ */
 int icc_disable(struct icc_path *path)
 {
 	return __icc_enable(path, false);

base-commit: 986c24e0fe44f844b44d365b71ce831947f50298
-- 
2.39.5 (Apple Git-154)

Re: [PATCH v2] interconnect: Add kernel-doc for devm_of_icc_get(), icc_enable() and icc_disable()

[Kuan-Wei Chiu]

On Sat, Sep 12, 2026 at 01:54:56PM +0200, Karl Mehltretter wrote:
> Documentation/driver-api/interconnect.rst lists devm_of_icc_get(),
> icc_enable() and icc_disable() in its kernel-doc directive for
> drivers/interconnect/core.c, but none of the three functions has a
> kernel-doc comment. The directive silently produces nothing for them, so
> the consumer API section of the rendered documentation never shows
> them.
> 
> Add kernel-doc comments in the style of the neighbouring functions.
> 
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>

Reviewed-by: Kuan-Wei Chiu <visitorckw@gmail.com>

Regards,
Kuan-Wei

> ---
> Changes in v2:
> - Describe @path as an interconnect path and explicitly state that
>   passing NULL is a no-op returning 0 for both icc_enable() and
>   icc_disable() (Kuan-Wei Chiu).
> 
> v1: https://lore.kernel.org/r/20260907020504.24783-1-kmehltretter@gmail.com/
> 
>  drivers/interconnect/core.c | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
> 
> diff --git a/drivers/interconnect/core.c b/drivers/interconnect/core.c
> index 4aa991a54101..802f07e806d5 100644
> --- a/drivers/interconnect/core.c
> +++ b/drivers/interconnect/core.c
> @@ -423,6 +423,17 @@ static void devm_icc_release(struct device *dev, void *res)
>  	icc_put(*(struct icc_path **)res);
>  }
>  
> +/**
> + * devm_of_icc_get() - get a path handle from a DT node based on name
> + * @dev: device pointer for the consumer device
> + * @name: interconnect path name
> + *
> + * This function is the resource managed version of of_icc_get(). The path
> + * is released with icc_put() automatically when @dev is unbound.
> + *
> + * Return: icc_path pointer on success or ERR_PTR() on error. NULL is returned
> + * when the API is disabled or the "interconnects" DT property is missing.
> + */
>  struct icc_path *devm_of_icc_get(struct device *dev, const char *name)
>  {
>  	struct icc_path **ptr, *path;
> @@ -786,12 +797,33 @@ static int __icc_enable(struct icc_path *path, bool enable)
>  			  path->reqs[0].peak_bw);
>  }
>  
> +/**
> + * icc_enable() - enable a path
> + * @path: interconnect path
> + *
> + * Mark all requests on the path as enabled and reapply the bandwidth that
> + * was last set with icc_set_bw().
> + * Passing a NULL @path is a no-op and returns 0.
> + *
> + * Return: 0 on success, or an appropriate error code otherwise.
> + */
>  int icc_enable(struct icc_path *path)
>  {
>  	return __icc_enable(path, true);
>  }
>  EXPORT_SYMBOL_GPL(icc_enable);
>  
> +/**
> + * icc_disable() - disable a path
> + * @path: interconnect path
> + *
> + * Mark all requests on the path as disabled, so that they no longer count
> + * towards the aggregated bandwidth, and reapply the constraints. The
> + * requested bandwidth is kept and restored by icc_enable().
> + * Passing a NULL @path is a no-op and returns 0.
> + *
> + * Return: 0 on success, or an appropriate error code otherwise.
> + */
>  int icc_disable(struct icc_path *path)
>  {
>  	return __icc_enable(path, false);
> 
> base-commit: 986c24e0fe44f844b44d365b71ce831947f50298
> -- 
> 2.39.5 (Apple Git-154)
>