[PATCH v2] gpu: ipu-v3: clean up kernel-doc warnings

[PATCH v2] gpu: ipu-v3: clean up kernel-doc warnings

[Randy Dunlap]

Correct all kernel-doc warnings:
- fix a typedef kernel-doc comment
- mark a list_head as private
- use Returns: for function return values

Warning: include/video/imx-ipu-image-convert.h:31 struct member 'list' not
 described in 'ipu_image_convert_run'
Warning: include/video/imx-ipu-image-convert.h:40 function parameter
 'ipu_image_convert_cb_t' not described in 'void'
Warning: include/video/imx-ipu-image-convert.h:40 expecting prototype for
 ipu_image_convert_cb_t(). Prototype was for void() instead
Warning: include/video/imx-ipu-image-convert.h:66 No description found for
 return value of 'ipu_image_convert_verify'
Warning: include/video/imx-ipu-image-convert.h:90 No description found for
 return value of 'ipu_image_convert_prepare'
Warning: include/video/imx-ipu-image-convert.h:125 No description found for
 return value of 'ipu_image_convert_queue'
Warning: include/video/imx-ipu-image-convert.h:163 No description found for
 return value of 'ipu_image_convert'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Philipp Zabel <p.zabel@pengutronix.de>
---
v2: add Reviewed-by, update Cc: list, rebase, resend

Cc: Philipp Zabel <p.zabel@pengutronix.de>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: David Airlie <airlied@gmail.com>
Cc: Simona Vetter <simona@ffwll.ch>
Cc: imx@lists.linux.dev
Cc: linux-arm-kernel@lists.infradead.org
Cc: Helge Deller <deller@gmx.de>
Cc: linux-fbdev@vger.kernel.org

 include/video/imx-ipu-image-convert.h |   16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

--- linux-next-20260218.orig/include/video/imx-ipu-image-convert.h
+++ linux-next-20260218/include/video/imx-ipu-image-convert.h
@@ -27,12 +27,13 @@ struct ipu_image_convert_run {
 
 	int status;
 
+	/* private: */
 	/* internal to image converter, callers don't touch */
 	struct list_head list;
 };
 
 /**
- * ipu_image_convert_cb_t - conversion callback function prototype
+ * typedef ipu_image_convert_cb_t - conversion callback function prototype
  *
  * @run:	the completed conversion run pointer
  * @ctx:	a private context pointer for the callback
@@ -60,7 +61,7 @@ void ipu_image_convert_adjust(struct ipu
  * @out:	output image format
  * @rot_mode:	rotation mode
  *
- * Returns 0 if the formats and rotation mode meet IPU restrictions,
+ * Returns: 0 if the formats and rotation mode meet IPU restrictions,
  * -EINVAL otherwise.
  */
 int ipu_image_convert_verify(struct ipu_image *in, struct ipu_image *out,
@@ -77,11 +78,11 @@ int ipu_image_convert_verify(struct ipu_
  * @complete:	run completion callback
  * @complete_context:	a context pointer for the completion callback
  *
- * Returns an opaque conversion context pointer on success, error pointer
+ * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.
+ *
+ * Returns: an opaque conversion context pointer on success, error pointer
  * on failure. The input/output formats and rotation mode must already meet
  * IPU retrictions.
- *
- * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.
  */
 struct ipu_image_convert_ctx *
 ipu_image_convert_prepare(struct ipu_soc *ipu, enum ipu_ic_task ic_task,
@@ -122,6 +123,8 @@ void ipu_image_convert_unprepare(struct
  * In V4L2, drivers should call ipu_image_convert_queue() while
  * streaming to queue the conversion of a received input buffer.
  * For example mem2mem devices this would be called in .device_run.
+ *
+ * Returns: 0 on success or -errno on error.
  */
 int ipu_image_convert_queue(struct ipu_image_convert_run *run);
 
@@ -155,6 +158,9 @@ void ipu_image_convert_abort(struct ipu_
  * On successful return the caller can queue more run requests if needed, using
  * the prepared context in run->ctx. The caller is responsible for unpreparing
  * the context when no more conversion requests are needed.
+ *
+ * Returns: pointer to the created &struct ipu_image_convert_run that has
+ * been queued on success; an ERR_PTR(errno) on error.
  */
 struct ipu_image_convert_run *
 ipu_image_convert(struct ipu_soc *ipu, enum ipu_ic_task ic_task,

Claude review: gpu: ipu-v3: clean up kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: gpu: ipu-v3: clean up kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 1
Reviewed: 2026-02-23T06:22:16.059906

---

This is a single patch (not a series) that cleans up kernel-doc warnings in `include/video/imx-ipu-image-convert.h`. The changes are purely documentation fixes:

1. Marking the `list` member as `/* private: */` to suppress the "not described" warning.
2. Fixing the typedef kernel-doc comment from `ipu_image_convert_cb_t` to `typedef ipu_image_convert_cb_t`.
3. Converting bare `Returns` to `Returns:` (with colon) to follow proper kernel-doc syntax for return value documentation.
4. Adding missing `Returns:` sections to `ipu_image_convert_queue()` and `ipu_image_convert()`.

The patch is straightforward and low-risk. It already carries a Reviewed-by from the subsystem maintainer (Philipp Zabel). No correctness, locking, or resource management concerns apply since only documentation comments are modified.

---
Generated by Claude Code Patch Reviewer

Claude review: gpu: ipu-v3: clean up kernel-doc warnings

[Claude Code Review Bot]

Patch Review

No functional issues. All changes are kernel-doc comment fixes that address the specific warnings listed in the commit message.

> +	/* private: */
>  	/* internal to image converter, callers don't touch */
>  	struct list_head list;

Correct use of the `/* private: */` kernel-doc annotation to suppress the warning about undocumented `list` member.

> - * ipu_image_convert_cb_t - conversion callback function prototype
> + * typedef ipu_image_convert_cb_t - conversion callback function prototype

Correct fix. Kernel-doc requires `typedef` for typedef documentation.

> - * Returns 0 if the formats and rotation mode meet IPU restrictions,
> + * Returns: 0 if the formats and rotation mode meet IPU restrictions,

Correct. Kernel-doc expects `Returns:` with a colon.

> - * Returns an opaque conversion context pointer on success, error pointer
> + * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.
> + *
> + * Returns: an opaque conversion context pointer on success, error pointer
>   * on failure. The input/output formats and rotation mode must already meet
>   * IPU retrictions.
> - *
> - * In V4L2, drivers should call ipu_image_convert_prepare() at streamon.

This moves the `In V4L2` note before `Returns:` so the return value documentation appears last. This is the correct kernel-doc convention -- `Returns:` should be the final section. One minor note: the pre-existing typo "retrictions" (should be "restrictions") survives this patch, but fixing it is outside the scope of a doc-format cleanup.

> + * Returns: 0 on success or -errno on error.

> + * Returns: pointer to the created &struct ipu_image_convert_run that has
> + * been queued on success; an ERR_PTR(errno) on error.

Both additions are accurate descriptions matching the function signatures and existing documentation prose.

No issues found. The patch is a clean documentation fix that addresses all seven kernel-doc warnings listed in the commit message.

---
Generated by Claude Code Patch Reviewer