RE: [PATCH 0/4] kernel-doc fix for headers

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 17 Mar 2026, "Lin, Shuicheng" <shuicheng.lin@intel.com> wrote:
> On Tue Mar 17, 2026 5:26 AM Jani Nikula wrote:
>> On Mon, 16 Mar 2026, Shuicheng Lin <shuicheng.lin@intel.com> wrote:
>> > Generated by AI and reviewed to confirm the change is correct.
>> > Split by category to ease review.
>> 
>> Will you also ask your AI why kernel-doc didn't warn about these in the regular
>> build?
>
> Ha. AI told me that kernel-doc script does not validate whether the name match or not.
> "
> Why kernel-doc Misses These
> 1. Inline member docs are stored as sections, not validated against C members. In kdoc_parser.py:1673-1676, when an inline doc like /** @format: ... */ is encountered during prototype parsing, it calls begin_section() and add_text(). The tag name is recorded but never cross-checked against the actual struct member on the next line.
> 2. check_sections() (kdoc_parser.py:661-674) only checks the other direction - it detects when a documented section name isn't in the parameter list, flagging "Excess" descriptions. But for nested members (those with . in the name, line 537), even the "not described" warning is suppressed.
> 3. Some structs aren't even parsed. For example, xe_oa_buffer uses /** @xe_oa_buffer: ... */ instead of /** struct xe_oa_buffer - ... */, so kernel-doc doesn't recognize it as a struct doc block at all.
> "
> And to fix it:
> "
> 3. Enhance scripts/kernel-doc itself
> The proper fix would be to add validation in kdoc_parser.py that cross-checks inline @member tags against the actual C struct member declared on the following line(s). Specifically:
> - In process_proto() around line 1673, after parsing doc_inline_oneline, read the next non-blank line to extract the actual member name and compare it to the @tag.
> - Handle dotted names like @outer.inner by checking the leaf component matches.
> "

Maybe take that on, then? We've got build checks to run kernel-doc, it's
a bummer if it doesn't catch the issues.

BR,
Jani.


>
> Shuicheng
>
>> 
>> BR,
>> Jani.
>> 
>> 
>> >
>> > Shuicheng Lin (4):
>> >   drm/xe: Fix stale and mismatched kernel-doc member tags in header
>> >     files
>> >   drm/xe: Add missing '@' prefix to kernel-doc member tags
>> >   drm/xe: Fix kernel-doc comment syntax issues in header files
>> >   drm/xe: Fix type and parameter name mismatches in kernel-doc
>> >     references
>> >
>> >  drivers/gpu/drm/xe/xe_device_types.h      | 6 +++---
>> >  drivers/gpu/drm/xe/xe_exec_queue_types.h  | 2 +-
>> > drivers/gpu/drm/xe/xe_gt_sriov_pf_types.h | 1 -
>> >  drivers/gpu/drm/xe/xe_gt_types.h          | 2 +-
>> >  drivers/gpu/drm/xe/xe_guc_capture_types.h | 2 +-
>> >  drivers/gpu/drm/xe/xe_guc_ct_types.h      | 4 ++--
>> >  drivers/gpu/drm/xe/xe_guc_relay_types.h   | 2 +-
>> >  drivers/gpu/drm/xe/xe_guc_submit_types.h  | 2 +-
>> >  drivers/gpu/drm/xe/xe_hw_engine_types.h   | 2 +-
>> >  drivers/gpu/drm/xe/xe_oa_types.h          | 8 +++++---
>> >  drivers/gpu/drm/xe/xe_pagefault_types.h   | 4 ++--
>> >  drivers/gpu/drm/xe/xe_pt_types.h          | 2 +-
>> >  drivers/gpu/drm/xe/xe_pt_walk.h           | 6 +++---
>> >  drivers/gpu/drm/xe/xe_vm_types.h          | 2 +-
>> >  14 files changed, 23 insertions(+), 22 deletions(-)
>> 
>> --
>> Jani Nikula, Intel

-- 
Jani Nikula, Intel