[PATCH] drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[PATCH] drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Randy Dunlap]

Add 2 struct member descriptions and demote several comments from
"/**" kernel-doc comments to plain C "/*" comments to eliminate all
kernel-doc warnings:

Warning: include/uapi/drm/tegra_drm.h:353 struct member 'cmdbuf' not
 described in 'drm_tegra_reloc'
Warning: include/uapi/drm/tegra_drm.h:353 struct member 'target' not
 described in 'drm_tegra_reloc'

Warning: include/uapi/drm/tegra_drm.h:780 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Specify that bit 39 of the patched-in address should be set to switch
Warning: include/uapi/drm/tegra_drm.h:832 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Execute `words` words of Host1x opcodes specified in the
 `gather_data_ptr`
Warning: include/uapi/drm/tegra_drm.h:837 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Wait for a syncpoint to reach a value before continuing with further
Warning: include/uapi/drm/tegra_drm.h:842 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Wait for a syncpoint to reach a value before continuing with further

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Thierry Reding <thierry.reding@gmail.com>
Cc: Mikko Perttunen <mperttunen@nvidia.com>
Cc: linux-tegra@vger.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>

 include/uapi/drm/tegra_drm.h |   10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

--- linux-next-20260226.orig/include/uapi/drm/tegra_drm.h
+++ linux-next-20260226/include/uapi/drm/tegra_drm.h
@@ -304,6 +304,7 @@ struct drm_tegra_cmdbuf {
  * struct drm_tegra_reloc - GEM object relocation structure
  */
 struct drm_tegra_reloc {
+	/** @cmdbuf: cmd information */
 	struct {
 		/**
 		 * @cmdbuf.handle:
@@ -321,6 +322,7 @@ struct drm_tegra_reloc {
 		 */
 		__u32 offset;
 	} cmdbuf;
+	/** @target: relocate target information */
 	struct {
 		/**
 		 * @target.handle:
@@ -777,7 +779,7 @@ struct drm_tegra_channel_unmap {
 
 /* Submission */
 
-/**
+/*
  * Specify that bit 39 of the patched-in address should be set to switch
  * swizzling between Tegra and non-Tegra sector layout on systems that store
  * surfaces in system memory in non-Tegra sector layout.
@@ -829,17 +831,17 @@ struct drm_tegra_submit_buf {
 	} reloc;
 };
 
-/**
+/*
  * Execute `words` words of Host1x opcodes specified in the `gather_data_ptr`
  * buffer. Each GATHER_UPTR command uses successive words from the buffer.
  */
 #define DRM_TEGRA_SUBMIT_CMD_GATHER_UPTR		0
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands.
  */
 #define DRM_TEGRA_SUBMIT_CMD_WAIT_SYNCPT		1
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands. The threshold is calculated relative to the start of the job.
  */

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 1
Reviewed: 2026-02-27T11:38:40.851349

---

This is a single-patch series from Randy Dunlap that fixes kernel-doc warnings in the Tegra DRM UAPI header. The patch is straightforward and correct — it addresses two categories of warnings:

1. Missing `@cmdbuf` and `@target` member descriptions in `struct drm_tegra_reloc`.
2. Comments on `#define` macros incorrectly using `/**` (kernel-doc) style instead of plain `/*` comments.

The patch is clean, minimal, and does exactly what the commit message describes. No functional changes, no UAPI ABI changes, no risk of breakage.

**Recommendation: Accept.** This is a routine documentation cleanup patch.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Patch Review

**Fix 1 & 2: Add missing struct member descriptions**

```c
 struct drm_tegra_reloc {
+	/** @cmdbuf: cmd information */
 	struct {
```

```c
 	} cmdbuf;
+	/** @target: relocate target information */
 	struct {
```

These additions are correct. The `struct drm_tegra_reloc` has kernel-doc (`/** ... */`) on the struct itself, and the nested anonymous struct members `cmdbuf.handle`, `cmdbuf.offset`, etc. are all documented, but the top-level `cmdbuf` and `target` aggregate members themselves were not. kernel-doc requires all direct struct members to be documented, so adding these one-line descriptions fixes the warnings.

Minor nit: the descriptions are somewhat terse ("cmd information", "relocate target information") — they could be slightly more descriptive (e.g., "command buffer reference" and "relocation target reference"), but this is a very minor style preference and not a blocker. The existing sub-member docs already provide the detail.

**Fix 3–6: Demote `/**` to `/*` on `#define` comments**

```c
-/**
+/*
  * Specify that bit 39 of the patched-in address should be set to switch
```

```c
-/**
+/*
  * Execute `words` words of Host1x opcodes specified in the `gather_data_ptr`
```

```c
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands.
```

```c
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands. The threshold is calculated relative to the start of the job.
```

All four are correct. `/**` signals kernel-doc format, which requires specific structured syntax (e.g., `@param:` descriptions for function parameters, or `DOC:` sections). These are free-form comments on `#define` macros, so `/*` is the appropriate style. The change silences the warnings without losing any documentation content.

**Reviewed-by: No issues found.** The patch is correct and ready to merge.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 2
Reviewed: 2026-03-05T13:56:54.726421

---

This is a single-patch series that fixes kernel-doc warnings in `include/uapi/drm/tegra_drm.h`. The patch addresses two categories of issues: (1) missing `@cmdbuf` and `@target` member descriptions in `struct drm_tegra_reloc`, and (2) `/**` comments on `#define` macros that aren't proper kernel-doc format. The fixes for the struct members look correct; however, the kernel-doc syntax used for the `#define` macros is wrong and will not resolve the warnings.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Patch Review

**Struct member fixes (correct):**

The additions at lines 108 and 116 of the patch are appropriate:

```c
+	/** @cmdbuf: cmd information */
	struct {
```

```c
+	/** @target: relocate target information */
	struct {
```

These correctly add the missing top-level member descriptions for the anonymous struct members `cmdbuf` and `target` within `struct drm_tegra_reloc`, resolving the first two warnings.

**#define macro doc-comments (incorrect syntax):**

The kernel-doc comments added for the `#define` constants use incorrect syntax. For example:

```c
/**
+ * define DRM_TEGRA_SUBMIT_RELOC_SECTOR_LAYOUT - \
+ *    Select sector layout swizzling for in-memory buffers.
+ *
  * Specify that bit 39 of the patched-in address should be set to switch
```

The correct kernel-doc syntax for a `#define` requires a leading `DOC:` tag or more typically for constants, simply converting `/**` to `/*` to suppress the warning. If the intent is to make these proper kernel-doc comments, the syntax should be:

```c
/**
 * DOC: DRM_TEGRA_SUBMIT_RELOC_SECTOR_LAYOUT
 *
 * Select sector layout swizzling ...
```

The `define MACRO_NAME - description` format used in this patch is not valid kernel-doc syntax. The kernel-doc script recognizes `@define` for macro-like entities but the format here (`define NAME - \`) doesn't match any recognized kernel-doc pattern. This will likely either still produce warnings or produce malformed documentation output.

The same issue applies to all three `DRM_TEGRA_SUBMIT_CMD_*` defines.

**Alternative fix:** If the goal is simply to silence the warnings (since these are simple constants, not function-like macros), the simplest approach is to change `/**` to `/*`, which avoids triggering the kernel-doc parser entirely while preserving the descriptive comments. This was effectively what v1 of Mikko's feedback was about — but if proper kernel-doc is desired, the `DOC:` form or the correct macro documentation syntax should be used.

**Minor nit:** The member description `cmd information` for `@cmdbuf` is quite vague. Something like `command buffer relocation info` would be more descriptive, though this is stylistic.

---
Generated by Claude Code Patch Reviewer