[PATCH v2] drm/sun4i: fix kernel-doc warnings in sunxi_engine.h

[PATCH v2] drm/sun4i: fix kernel-doc warnings in sunxi_engine.h

[Randy Dunlap]

Correct the kernel-doc notation, add a missing struct member comment,
and add a missing "Returns:" function comment to eliminate kernel-doc
warnings:

Warning: drivers/gpu/drm/sun4i/sunxi_engine.h:116 Incorrect use of
 kernel-doc format: * @mode_set
Warning: drivers/gpu/drm/sun4i/sunxi_engine.h:125 struct member 'mode_set'
 not described in 'sunxi_engine_ops'
Warning: drivers/gpu/drm/sun4i/sunxi_engine.h:144 struct member 'list'
 not described in 'sunxi_engine'
Warning: drivers/gpu/drm/sun4i/sunxi_engine.h:168 No description found
 for return value of 'sunxi_engine_layers_init'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Chen-Yu Tsai <wens@kernel.org>
---
v2: add Reviewed-by & resend

Cc: Chen-Yu Tsai <wens@kernel.org>
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: Jernej Skrabec <jernej.skrabec@gmail.com>
Cc: Samuel Holland <samuel@sholland.org>
Cc: linux-arm-kernel@lists.infradead.org
Cc: linux-sunxi@lists.linux.dev
---
 drivers/gpu/drm/sun4i/sunxi_engine.h |    7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

--- linux-next-20260218.orig/drivers/gpu/drm/sun4i/sunxi_engine.h
+++ linux-next-20260218/drivers/gpu/drm/sun4i/sunxi_engine.h
@@ -114,7 +114,7 @@ struct sunxi_engine_ops {
 	void (*vblank_quirk)(struct sunxi_engine *engine);
 
 	/**
-	 * @mode_set
+	 * @mode_set:
 	 *
 	 * This callback is used to set mode related parameters
 	 * like interlacing, screen size, etc. once per mode set.
@@ -131,6 +131,7 @@ struct sunxi_engine_ops {
  * @node:	the of device node of the engine
  * @regs:	the regmap of the engine
  * @id:		the id of the engine (-1 if not used)
+ * @list:	engine list management
  */
 struct sunxi_engine {
 	const struct sunxi_engine_ops	*ops;
@@ -140,7 +141,6 @@ struct sunxi_engine {
 
 	int id;
 
-	/* Engine list management */
 	struct list_head		list;
 };
 
@@ -163,6 +163,9 @@ sunxi_engine_commit(struct sunxi_engine
  * sunxi_engine_layers_init() - Create planes (layers) for the engine
  * @drm:	pointer to the drm_device for which planes will be created
  * @engine:	pointer to the engine
+ *
+ * Returns: The array of struct drm_plane backing the layers, or an
+ *		error pointer on failure.
  */
 static inline struct drm_plane **
 sunxi_engine_layers_init(struct drm_device *drm, struct sunxi_engine *engine)

Claude review: drm/sun4i: fix kernel-doc warnings in sunxi_engine.h

[Claude Code Review Bot]

Overall Series Review

Subject: drm/sun4i: fix kernel-doc warnings in sunxi_engine.h
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 1
Reviewed: 2026-02-23T06:20:10.068776

---

This is a single-patch series that fixes four kernel-doc warnings in `drivers/gpu/drm/sun4i/sunxi_engine.h`. The changes are purely documentation: adding a missing colon to a struct member doc tag, converting an inline comment to a proper kernel-doc `@list` member description, and adding a missing `Returns:` section to `sunxi_engine_layers_init()`.

The patch is minimal, correct, and already carries a Reviewed-by from Chen-Yu Tsai (the sun4i maintainer). There are no functional code changes and no concerns.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/sun4i: fix kernel-doc warnings in sunxi_engine.h

[Claude Code Review Bot]

Patch Review

No issues found. All four kernel-doc warnings are addressed correctly:

> -	 * @mode_set
> +	 * @mode_set:

Adds the missing colon required by kernel-doc notation for struct member descriptions.

> + * @list:	engine list management

Promotes the existing inline comment `/* Engine list management */` to a proper kernel-doc `@list` member description in the struct's doc block, and removes the now-redundant inline comment:

> -	/* Engine list management */
>  	struct list_head		list;

This is the right approach — the description is moved up into the kernel-doc block where tooling expects it.

> + * Returns: The array of struct drm_plane backing the layers, or an
> + *		error pointer on failure.

The `Returns:` description for `sunxi_engine_layers_init()` is accurate — the function returns either the result of `ops->layers_init()` or `ERR_PTR(-ENOSYS)`, which matches "an error pointer on failure."

Clean patch, no concerns.

---
Generated by Claude Code Patch Reviewer