From nobody Tue Oct 7 10:38:21 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 E0BE13093BC; Thu, 10 Jul 2025 23:31:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190320; cv=none; b=UtDeePYCgPMNrSShGt/kkVJ9y2VdATy/jcdkzmXK6p22JOV9QbUAy5vNVYw70C69EliP7iq2B3T6/xdZlu/iDOekPnGeCUye8420FiUuuB1GxTGwH2198Tr8LmvNAwvqLo5ztCZqTyaPrBAKquHoIpxs1gZSTi2JsmpI1I34Pjc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190320; c=relaxed/simple; bh=dECE7HmGYRkH+wFN9HM0uf4VtBgfKt5FWt2EPDfKnrU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TO06lNnAjKt9uNTHL6j7FdyBKDQUmjnWTGogs/W9nSZ/oGevLjH5O+5NENWQJf5+JEE10Uh4JtyRuywFbyhwsW9yKx/Rnv9LL4W21GhSPv6vqjlFHq4ZkXhnBGWjBVYkAOAlOSpBus+UGpZP1E9F+MhKLv3mfycEv/WbjXqmi6I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=jHj5Q8u1; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="jHj5Q8u1" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 38BD540AB5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190318; bh=nPOfJuokmVPpEF/4Hc1zpZaBuvlA3dKu+HWEiyN98XE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jHj5Q8u1vBkg9Zkb2jHuyUCURSzP5asEjJi4ROq0PLwmRJvM6PF5mggcJt8R+zF/t FXC6X9gyypTr5pUEQTot32ryGefynXaeQYGJ/Y6u5DQr0N4cJCEIKsdkTz7/7PkLmy W3a5uIGSPdd0s2CtTUGat+CdZCwelBXdnxxlKkiCbYrLSOT7wbVcebk88pYUF9NEPt 5z2uP1+CnlmrP8AmX0VNSm07x0fZD8j7x8cD0ZBtXkV8TRmTDaw8ufT0jmmv8hgauX zrtJ7OnIAQBcx5D5HSh49mEPpa0QpDsryiQVIUbjhBcmhdPFTIY7cTwiH36O7nNI9O We0FAKmXwLaJg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 38BD540AB5; Thu, 10 Jul 2025 23:31:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 11/12] docs: kdoc: clean up check_sections() Date: Thu, 10 Jul 2025 17:31:41 -0600 Message-ID: <20250710233142.246524-12-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> 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" entry.sectcheck is just a duplicate of our list of sections that is only passed to check_sections(); its main purpose seems to be to avoid checking the special named sections. Rework check_sections() to not use that field (which is then deleted), tocheck for the known sections directly, and tighten up the logic in general. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 7191fa94e17a..fdde14b045fe 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -42,9 +42,11 @@ doc_decl =3D doc_com + KernRe(r'(\w+)', cache=3DFalse) # @{section-name}: # while trying to not match literal block starts like "example::" # +known_section_names =3D 'description|context|returns?|notes?|examples?' +known_sections =3D KernRe(known_section_names, flags =3D re.I) doc_sect =3D doc_com + \ - KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|no= tes?|examples?)\s*:([^:].*)?$', - flags=3Dre.I, cache=3DFalse) + KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].= *)?$', + flags=3Dre.I, cache=3DFalse) =20 doc_content =3D doc_com_body + KernRe(r'(.*)', cache=3DFalse) doc_inline_start =3D KernRe(r'^\s*/\*\*\s*$', cache=3DFalse) @@ -115,7 +117,6 @@ class KernelEntry: self.config =3D config =20 self._contents =3D [] - self.sectcheck =3D "" self.prototype =3D "" =20 self.warnings =3D [] @@ -187,7 +188,6 @@ class KernelEntry: self.parameterdescs[name] =3D contents self.parameterdesc_start_lines[name] =3D self.new_start_line =20 - self.sectcheck +=3D name + " " self.new_start_line =3D 0 =20 else: @@ -478,29 +478,20 @@ class KernelDoc: self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 - def check_sections(self, ln, decl_name, decl_type, sectcheck): + def check_sections(self, ln, decl_name, decl_type): """ Check for errors inside sections, emitting warnings if not found parameters are described. """ - - sects =3D sectcheck.split() - - for sx in range(len(sects)): # pylint: disable=3D= C0200 - err =3D True - for param in self.entry.parameterlist: - if param =3D=3D sects[sx]: - err =3D False - break - - if err: + for section in self.entry.sections: + if section not in self.entry.parameterlist and \ + not known_sections.search(section): 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} '{sects[sx]}' description i= n '{decl_name}'") + f"Excess {dname} '{section}' description in = '{decl_name}'") =20 def check_return_section(self, ln, declaration_name, return_type): """ @@ -754,7 +745,7 @@ class KernelDoc: =20 self.create_parameter_list(ln, decl_type, members, ';', declaration_name) - self.check_sections(ln, declaration_name, decl_type, self.entry.se= ctcheck) + self.check_sections(ln, declaration_name, decl_type) =20 # Adjust declaration for better display declaration =3D KernRe(r'([\{;])').sub(r'\1\n', declaration) @@ -1018,7 +1009,7 @@ class KernelDoc: f"expecting prototype for {self.entry.identifier= }(). Prototype was for {declaration_name}() instead") return =20 - self.check_sections(ln, declaration_name, "function", self.entry.s= ectcheck) + self.check_sections(ln, declaration_name, "function") =20 self.check_return_section(ln, declaration_name, return_type) =20 --=20 2.49.0