From nobody Tue Jun 16 03:47:15 2026 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.8]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6F699335064 for ; Wed, 15 Apr 2026 21:51:51 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.8 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776289912; cv=none; b=oLsw9ij2CP9sQhSFQCpqoTGe2GGdsp3Uy0/alLIK06NrR35+vMwa43c+kLmb2PeGPgrrxdqjtOyS74zeHXG0YH0bWnQqza6u2aTLgjf2dCTqDFir9/QZkel8xVmH91Wm3O5yXL4UANyHZm9FfRYSTigZ2gETHpv8wZ64URT109M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776289912; c=relaxed/simple; bh=WIJ4lRxewKQJWEMFaGMuKYzmsOI1W4hZJrmSXQVtt88=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=mFHr5GYPuSyv3ZbAsfEgaUZP1WTv9VkdoFTwIa1SCCvO95ji8IpJYKZdyu1X3fHtVO1CkGOfVsxgNjijBCGG/mgUdDsT9Rimfen3B5iMY+yyPbDSVR516Db4vBgXCvo/DX+/XUYcB769typx7vNVFMgnvE9gom3K4N1Q0+jOMVk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com; spf=pass smtp.mailfrom=intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=CQQXn3Nk; arc=none smtp.client-ip=192.198.163.8 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="CQQXn3Nk" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1776289910; x=1807825910; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=WIJ4lRxewKQJWEMFaGMuKYzmsOI1W4hZJrmSXQVtt88=; b=CQQXn3NkYQTQQAXdl6KRkr95pmWKfle5wffC1+JA2x49OqVO/JEA4wVq /NjZ+ANbdiqfmlY2MWvESRLuXLZFM4KKIKquhqcRS03dXwjer+KvNaUz1 FDlp1fxBYCba8r+/nDoV3i0uuF7rWmgy3piJ8IlkMTJNxD6DlizwBaA3e DmXTLos10ZIxVFc99DQBukVYrSXJJdi6+3HW85FWewYFtTzc2T4WLKCqn Me8DDcMkG6xT6KA024Rr1E720AS/85kU6qxEwN360e3zR74JoVqrIVy3/ f+YBeQ2MoCe7Y7WgCq3xiqmd88hLX4uvM3pEE8zNgmoCStuJQkh1yeB2u Q==; X-CSE-ConnectionGUID: MJiBmKR5Sr2EiTuB4egASg== X-CSE-MsgGUID: oRN4D2bxS3eNnoX3klIQgw== X-IronPort-AV: E=McAfee;i="6800,10657,11760"; a="94851306" X-IronPort-AV: E=Sophos;i="6.23,181,1770624000"; d="scan'208";a="94851306" Received: from orviesa005.jf.intel.com ([10.64.159.145]) by fmvoesa102.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 15 Apr 2026 14:51:50 -0700 X-CSE-ConnectionGUID: tvO55GaxTzu3okF5vKXcGw== X-CSE-MsgGUID: +jAmcziIQhaTe5xFnPcPPw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.23,181,1770624000"; d="scan'208";a="235493092" Received: from osgcshtiger.sh.intel.com ([10.239.81.49]) by orviesa005.jf.intel.com with ESMTP; 15 Apr 2026 14:51:50 -0700 From: Shuicheng Lin To: linux-kernel@vger.kernel.org, intel-xe@lists.freedesktop.org Cc: Shuicheng Lin Subject: [PATCH] scripts/kernel-doc: Detect mismatched inline member documentation tags Date: Wed, 15 Apr 2026 21:50:32 +0000 Message-Id: <20260415215032.3398330-1-shuicheng.lin@intel.com> X-Mailer: git-send-email 2.34.1 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add validation in check_sections() to verify that inline member documentation tags (/** @member: description */) match actual struct/union member names. Previously, kernel-doc only validated section headers against the parameter list, but inline doc tags stored in parameterdescs were never cross-checked, allowing stale or mistyped member names to go undetected. The new check iterates over parameterdescs keys and warns about any that don't appear in the parameter list, catching issues like renamed struct members where the documentation tag was not updated to match. This catches real issues such as: - xe_bo_types.h: @atomic_access (missing struct prefix, should be @attr.atomic_access) - xe_device_types.h: @usm.asid (member is actually asid_to_vm) Assisted-by: Claude:claude-opus-4.6 Signed-off-by: Shuicheng Lin --- tools/lib/python/kdoc/kdoc_parser.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index ca00695b47b3..f21f06c0a9b0 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -673,6 +673,31 @@ class KernelDoc: self.emit_msg(ln, f"Excess {dname} '{section}' description in = '{decl_name}'") =20 + # + # Check that documented parameter names (from doc comments, includ= ing + # inline ``/** @member: */`` tags) actually match real members in + # the declaration. This catches mismatched or stale kernel-doc + # member tags that don't correspond to any actual struct/union + # member or function parameter. + # + for param_name, desc in self.entry.parameterdescs.items(): + # Skip auto-generated entries from push_parameter() + if desc =3D=3D self.undescribed: + continue + if desc in ("no arguments", "anonymous\n", "variable arguments= "): + continue + if param_name.startswith("{unnamed_"): + continue + if param_name in self.entry.parameterlist: + continue + + if decl_type =3D=3D 'function': + dname =3D f"{decl_type} parameter" + else: + dname =3D f"{decl_type} member" + self.emit_msg(ln, + f"Excess {dname} '{param_name}' description in '= {decl_name}'") + def check_return_section(self, ln, declaration_name, return_type): """ If the function doesn't return void, warns about the lack of a --=20 2.43.0