From nobody Fri Dec 19 16:00:45 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 53C65212FB3; Tue, 15 Apr 2025 03:13:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; cv=none; b=GZOdL/HbqZ8oKTU3bUR9DTPENYHig3XAWlK2jEXwjmWk4lwcwVEyhyK1uqkARC3vxtu3Alu8s1DIfMKKdXKH/IrXjjZNUOExXwsOcFmx9Of3WLH639AcMpbL0EhZ/7A4z66uSslNB+TpGWHEaPJnbAWXUCn1eTJvFmjoqZWqFSA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; c=relaxed/simple; bh=+p0de2nK08IJUNkWKnZ2hUub4wqLuqIa0QBeJgsqMJI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=p4B9UGnwBYSKjPxXAXoBTqqP+VqZ2qkXtMtSWNrL0sQdVR8/TewC4DDTpYDih4x3/XpABg8bgF2TE3yt3VKydBo+Q1nG6zSu8hMJUCEakZxoCadKbqdOoacVnjytdRPmExvAunOSQA9Pvytv84RqtUZspmGmHh6jaVg3+sefEJM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=S6mUBNXX; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="S6mUBNXX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BD996C4CEEB; Tue, 15 Apr 2025 03:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1744686799; bh=+p0de2nK08IJUNkWKnZ2hUub4wqLuqIa0QBeJgsqMJI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=S6mUBNXXJvrHcnDdmS6V8pEUa0PNOvNOMEtD8gmuvwfk++DmBYDsALFL71Wb0IaMP ik+ipXVY/GjwvNF2DKnqxcUr6El/oRrD5y3U2Act8+eTzRCn8u6Ioc3uC3mLeCCX4e ON2NIbHxVVUBWGalmCVcM34Eg70Ypoy6pBJswpqS1zr4dly+BuC9cdsR5E4ocbTdGh SbDC4p+rDkspf7hb7TXn/Kxkp9zZa0d0zvs90AnEUUquN52D/nq2DCwNsnLhhu1MDQ PFo5u6Og0g8aX1iYabA0tj4Sx3wn3i7Mya4/SpHP+Ji7P+uG+9V9Rv5HROENVUbL/+ hboahppDYCBcg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1u4WjU-00000002FHD-3pPT; Tue, 15 Apr 2025 11:13:08 +0800 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , linux-kernel@vger.kernel.org Subject: [PATCH 1/4] scripts/lib/kdoc/kdoc_files.py: don't try to join None Date: Tue, 15 Apr 2025 11:12:48 +0800 Message-ID: <4334d16f14cfd93e611b290fb56c35d236cadcb7.1744685912.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.0 In-Reply-To: References: 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 Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" If out_msg() returns None, it means that an unknown declaration was found. Avoid letting the script crash on such case. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_files.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index dd003feefd1b..2e51e5f3bb77 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -270,13 +270,16 @@ class KernelFiles(): =20 msg =3D "" for name, arg in self.results[fname]: - msg +=3D self.out_msg(fname, name, arg) + m =3D self.out_msg(fname, name, arg) =20 - if msg is None: + if m is None: ln =3D arg.get("ln", 0) dtype =3D arg.get('type', "") =20 self.config.log.warning("%s:%d Can't handle %s", fname, ln, dtype) + else: + msg +=3D m + if msg: yield fname, msg --=20 2.49.0 From nobody Fri Dec 19 16:00:45 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 B0C612147F2; Tue, 15 Apr 2025 03:13:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; cv=none; b=XkK3wGCyj7Gm0GLgXweSsKitqWpZ+R54ijJhvZANYfl68NzgEy8OjLuNkAe7DAptAwd6AaHOLYUNbQS5m4LT93kp638rK16qb5cOkNEp3Sgi7NDbv8O81ybSP+9cqGUhKj7vOeIYltmbK8U7evL32bz3HNzm7ssybFmC+ikiegQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; c=relaxed/simple; bh=cBxfVJXfS6rXbTztBE/vjmAWRsDhtuQ7i5IC2EtKpNw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=JogVbZFx89HpR7/wyzpMhp66n4Bp4uAbPPaz6fAYg+G7+do+SoarnupW8BtjuzXlWmY03XgeeDwX4f/KLlnySvN+ox9JpqftYGSbzgiowg6deRZA5MdEl+IBgvacd90NrgD37LQ+vd+5f9w0d+LtbD86PjiLOWJJl6IgCZFMKpY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pVeB+4ZU; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="pVeB+4ZU" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C2189C4AF09; Tue, 15 Apr 2025 03:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1744686800; bh=cBxfVJXfS6rXbTztBE/vjmAWRsDhtuQ7i5IC2EtKpNw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pVeB+4ZUhN+sVHOYldvnNSWVqP3OTRIEeOgtf6BpLWNVNwxR8xiy8tmkLa05vukqP CHzjdg7Dt+/8qoKiMVYQJAB8ZEfVy2XG3ZDKJLeC3did31PQLyWzBV160Bbhr+fCtx qZLYwN9hrLpYlf0WeprhMz3mfF8GozDiQsKrLkcQQakVc9acnAAWtr7DB/bon1wSH1 CbeI4p8XPo9G27JGyYgJ63295/Opx4GYnppeULB0DFa1SIhpCOpAqdsUf7bki88Jk0 aBEu8cx7+TW5m7zluhGGrGVFnHZqw/HgbjalQDbyL+kJNQ+EBkoIqtDmwtYlNVR1kV TPunRPJHsUvow== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1u4WjU-00000002FHG-3vES; Tue, 15 Apr 2025 11:13:08 +0800 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , Sean Anderson , linux-kernel@vger.kernel.org Subject: [PATCH 2/4] scripts/lib/kdoc/kdoc_parser.py: move states to a separate class Date: Tue, 15 Apr 2025 11:12:49 +0800 Message-ID: <00cb4e0b8a1545bf7c4401b58213841db5cba2e2.1744685912.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.0 In-Reply-To: References: 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 Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" States are really enums. on Python, enums are actually classes, as can be seen at: https://docs.python.org/3/library/enum.html Yet, I can't see any advantage of derivating the class from enum class here. So, just place the states on a separate class. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 119 +++++++++++++++++--------------- 1 file changed, 62 insertions(+), 57 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 4f036c720b36..461e0acb0fb7 100755 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -61,24 +61,22 @@ export_symbol_ns =3D KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL= )?\s*\(\s*(\w+)\s*,\s*"\S+" =20 type_param =3D KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=3DFalse) =20 - -class KernelDoc: +class state: """ - Read a C language source or header FILE and extract embedded - documentation comments. + State machine enums """ =20 # Parser states - STATE_NORMAL =3D 0 # normal code - STATE_NAME =3D 1 # looking for function name - STATE_BODY_MAYBE =3D 2 # body - or maybe more description - STATE_BODY =3D 3 # the body of the comment - STATE_BODY_WITH_BLANK_LINE =3D 4 # the body which has a blank line - STATE_PROTO =3D 5 # scanning prototype - STATE_DOCBLOCK =3D 6 # documentation block - STATE_INLINE =3D 7 # gathering doc outside main block + NORMAL =3D 0 # normal code + NAME =3D 1 # looking for function name + BODY_MAYBE =3D 2 # body - or maybe more description + BODY =3D 3 # the body of the comment + BODY_WITH_BLANK_LINE =3D 4 # the body which has a blank line + PROTO =3D 5 # scanning prototype + DOCBLOCK =3D 6 # documentation block + INLINE =3D 7 # gathering doc outside main block =20 - st_name =3D [ + name =3D [ "NORMAL", "NAME", "BODY_MAYBE", @@ -90,15 +88,15 @@ class KernelDoc: ] =20 # Inline documentation state - STATE_INLINE_NA =3D 0 # not applicable ($state !=3D STATE_INLINE) - STATE_INLINE_NAME =3D 1 # looking for member name (@foo:) - STATE_INLINE_TEXT =3D 2 # looking for member documentation - STATE_INLINE_END =3D 3 # done - STATE_INLINE_ERROR =3D 4 # error - Comment without header was found. - # Spit a warning as it's not - # proper kernel-doc and ignore the rest. + INLINE_NA =3D 0 # not applicable ($state !=3D INLINE) + INLINE_NAME =3D 1 # looking for member name (@foo:) + INLINE_TEXT =3D 2 # looking for member documentation + INLINE_END =3D 3 # done + INLINE_ERROR =3D 4 # error - Comment without header was found. + # Spit a warning as it's not + # proper kernel-doc and ignore the rest. =20 - st_inline_name =3D [ + inline_name =3D [ "", "_NAME", "_TEXT", @@ -106,6 +104,13 @@ class KernelDoc: "_ERROR", ] =20 + +class KernelDoc: + """ + Read a C language source or header FILE and extract embedded + documentation comments. + """ + # Section names =20 section_default =3D "Description" # default section @@ -122,8 +127,8 @@ class KernelDoc: self.config =3D config =20 # Initial state for the state machines - self.state =3D self.STATE_NORMAL - self.inline_doc_state =3D self.STATE_INLINE_NA + self.state =3D state.NORMAL + self.inline_doc_state =3D state.INLINE_NA =20 # Store entry currently being processed self.entry =3D None @@ -260,8 +265,8 @@ class KernelDoc: self.entry.leading_space =3D None =20 # State flags - self.state =3D self.STATE_NORMAL - self.inline_doc_state =3D self.STATE_INLINE_NA + self.state =3D state.NORMAL + self.inline_doc_state =3D state.INLINE_NA self.entry.brcount =3D 0 =20 self.entry.in_doc_sect =3D False @@ -1166,7 +1171,7 @@ class KernelDoc: self.entry.in_doc_sect =3D False =20 # next line is always the function name - self.state =3D self.STATE_NAME + self.state =3D state.NAME =20 def process_name(self, ln, line): """ @@ -1182,7 +1187,7 @@ class KernelDoc: self.entry.section =3D doc_block.group(1) =20 self.entry.identifier =3D self.entry.section - self.state =3D self.STATE_DOCBLOCK + self.state =3D state.DOCBLOCK return =20 if doc_decl.search(line): @@ -1224,7 +1229,7 @@ class KernelDoc: =20 self.entry.identifier =3D self.entry.identifier.strip(" ") =20 - self.state =3D self.STATE_BODY + self.state =3D state.BODY =20 # if there's no @param blocks need to set up default section h= ere self.entry.section =3D self.section_default @@ -1238,14 +1243,14 @@ class KernelDoc: r =3D KernRe(r"\s+") self.entry.descr =3D r.sub(" ", self.entry.descr) self.entry.declaration_purpose =3D self.entry.descr - self.state =3D self.STATE_BODY_MAYBE + self.state =3D state.BODY_MAYBE else: self.entry.declaration_purpose =3D "" =20 if not self.entry.is_kernel_comment: self.emit_warning(ln, f"This comment starts with '/**', but is= n't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{li= ne}") - self.state =3D self.STATE_NORMAL + self.state =3D state.NORMAL =20 if not self.entry.declaration_purpose and self.config.wshort_d= esc: self.emit_warning(ln, @@ -1254,7 +1259,7 @@ class KernelDoc: if not self.entry.identifier and self.entry.decl_type !=3D "en= um": self.emit_warning(ln, f"wrong kernel-doc identifier on line:\n= {line}") - self.state =3D self.STATE_NORMAL + self.state =3D state.NORMAL =20 if self.config.verbose: self.emit_warning(ln, @@ -1271,7 +1276,7 @@ class KernelDoc: STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. """ =20 - if self.state =3D=3D self.STATE_BODY_WITH_BLANK_LINE: + if self.state =3D=3D state.BODY_WITH_BLANK_LINE: r =3D KernRe(r"\s*\*\s?\S") if r.match(line): self.dump_section() @@ -1311,7 +1316,7 @@ class KernelDoc: if self.entry.contents: self.entry.contents +=3D "\n" =20 - self.state =3D self.STATE_BODY + self.state =3D state.BODY return =20 if doc_end.search(line): @@ -1325,7 +1330,7 @@ class KernelDoc: self.entry.prototype =3D "" self.entry.new_start_line =3D ln + 1 =20 - self.state =3D self.STATE_PROTO + self.state =3D state.PROTO return =20 if doc_content.search(line): @@ -1336,16 +1341,16 @@ class KernelDoc: self.dump_section() =20 self.entry.new_start_line =3D ln - self.state =3D self.STATE_BODY + self.state =3D state.BODY else: if self.entry.section !=3D self.section_default: - self.state =3D self.STATE_BODY_WITH_BLANK_LINE + self.state =3D state.BODY_WITH_BLANK_LINE else: - self.state =3D self.STATE_BODY + self.state =3D state.BODY =20 self.entry.contents +=3D "\n" =20 - elif self.state =3D=3D self.STATE_BODY_MAYBE: + elif self.state =3D=3D state.BODY_MAYBE: =20 # Continued declaration purpose self.entry.declaration_purpose =3D self.entry.declaration_= purpose.rstrip() @@ -1388,7 +1393,7 @@ class KernelDoc: def process_inline(self, ln, line): """STATE_INLINE: docbook comments within a prototype.""" =20 - if self.inline_doc_state =3D=3D self.STATE_INLINE_NAME and \ + if self.inline_doc_state =3D=3D state.INLINE_NAME and \ doc_inline_sect.search(line): self.entry.section =3D doc_inline_sect.group(1) self.entry.new_start_line =3D ln @@ -1397,7 +1402,7 @@ class KernelDoc: if self.entry.contents !=3D "": self.entry.contents +=3D "\n" =20 - self.inline_doc_state =3D self.STATE_INLINE_TEXT + self.inline_doc_state =3D state.INLINE_TEXT # Documentation block end */ return =20 @@ -1405,21 +1410,21 @@ class KernelDoc: if self.entry.contents not in ["", "\n"]: self.dump_section() =20 - self.state =3D self.STATE_PROTO - self.inline_doc_state =3D self.STATE_INLINE_NA + self.state =3D state.PROTO + self.inline_doc_state =3D state.INLINE_NA return =20 if doc_content.search(line): - if self.inline_doc_state =3D=3D self.STATE_INLINE_TEXT: + if self.inline_doc_state =3D=3D state.INLINE_TEXT: self.entry.contents +=3D doc_content.group(1) + "\n" if not self.entry.contents.strip(" ").rstrip("\n"): self.entry.contents =3D "" =20 - elif self.inline_doc_state =3D=3D self.STATE_INLINE_NAME: + elif self.inline_doc_state =3D=3D state.INLINE_NAME: self.emit_warning(ln, f"Incorrect use of kernel-doc format: {l= ine}") =20 - self.inline_doc_state =3D self.STATE_INLINE_ERROR + self.inline_doc_state =3D state.INLINE_ERROR =20 def syscall_munge(self, ln, proto): # pylint: disable=3DW0613 """ @@ -1598,8 +1603,8 @@ class KernelDoc: self.dump_section(start_new=3DFalse) =20 elif doc_inline_start.search(line): - self.state =3D self.STATE_INLINE - self.inline_doc_state =3D self.STATE_INLINE_NAME + self.state =3D state.INLINE + self.inline_doc_state =3D state.INLINE_NAME =20 elif self.entry.decl_type =3D=3D 'function': self.process_proto_function(ln, line) @@ -1663,7 +1668,7 @@ class KernelDoc: line =3D line.expandtabs().strip("\n") =20 # Group continuation lines on prototypes - if self.state =3D=3D self.STATE_PROTO: + if self.state =3D=3D state.PROTO: if line.endswith("\\"): prev +=3D line.rstrip("\\") cont =3D True @@ -1681,8 +1686,8 @@ class KernelDoc: prev_ln =3D None =20 self.config.log.debug("%d %s%s: %s", - ln, self.st_name[self.state], - self.st_inline_name[self.inline_= doc_state], + ln, state.name[self.state], + state.inline_name[self.inline_do= c_state], line) =20 # This is an optimization over the original script. @@ -1696,18 +1701,18 @@ class KernelDoc: self.process_export(export_table, line) =20 # Hand this line to the appropriate state handler - if self.state =3D=3D self.STATE_NORMAL: + if self.state =3D=3D state.NORMAL: self.process_normal(ln, line) - elif self.state =3D=3D self.STATE_NAME: + elif self.state =3D=3D state.NAME: self.process_name(ln, line) - elif self.state in [self.STATE_BODY, self.STATE_BODY_M= AYBE, - self.STATE_BODY_WITH_BLANK_LINE]: + elif self.state in [state.BODY, state.BODY_MAYBE, + state.BODY_WITH_BLANK_LINE]: self.process_body(ln, line) - elif self.state =3D=3D self.STATE_INLINE: # scanning = for inline parameters + elif self.state =3D=3D state.INLINE: # scanning for i= nline parameters self.process_inline(ln, line) - elif self.state =3D=3D self.STATE_PROTO: + elif self.state =3D=3D state.PROTO: self.process_proto(ln, line) - elif self.state =3D=3D self.STATE_DOCBLOCK: + elif self.state =3D=3D state.DOCBLOCK: self.process_docblock(ln, line) except OSError: self.config.log.error(f"Error: Cannot open file {self.fname}") --=20 2.49.0 From nobody Fri Dec 19 16:00:45 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 5FEA12DFA41; Tue, 15 Apr 2025 03:13:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686799; cv=none; b=t6DtKMkspY/cVM3GOqOxmMwaZ+PAjCYh3ZU2yYjYW34O1xRpdshUqPbI5C4vwyPUP6bD7wPm3pnmwBphdeTT2zS6b7mV1yqKnajKgx1LRchqSElf4f5/hLJZ5QAyDagx9hJiSH7S0vV0DUFbGG1/2f6Mahq6v/+V9FJToRpxzTk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686799; c=relaxed/simple; bh=h3uu4qXBIkG9b6aYOyE2Bexh5w2J8hSXMd0ynXOv4iU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AvxgQnxPJDz8e/0YBgXcBLvkxMXr7dAejT5X6im15L8BUdO5I9UwUzA5Ullfjd3+p+a0XCrxZzg9kqOj0RLjMOSqaEx1M0x59eVPbBd9ab/9VTx2xTNU2j6TS0aCRJ3nf2QZgFbk/EA3WdpHmwLoZzUTfU/k9fyh8h3ezEU/ICo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZNOfDGn7; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZNOfDGn7" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CBFB0C4CEE2; Tue, 15 Apr 2025 03:13:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1744686798; bh=h3uu4qXBIkG9b6aYOyE2Bexh5w2J8hSXMd0ynXOv4iU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZNOfDGn7S+3D5YO8rRh+0AA6NKTwHXAqJiaqhn2AP7vf4iSiMTnAQWrkfvrL1d4xs NAYO5Yfr3l9SgiXnKNXX8nTyuP3hspUqR93UfHeEGj8lUKtuicfDAqQjdaB81T/Y+i +pHXYDqNqXM2dz8qdjPlC0vCDz6xgKllki5kBcI6yG4BnrbYFMrkwNZ4i8Kx3Tb8Xs gi8vSh6aR66PDpJsxS9hpwxJtETY4Aa7/ofoXKx7Nitvm6XWPBj9LpSEmSGpfKD5Ly upd7deRRzp8lA4jUGkPZsPVocdMCeHZkUkYR7FMJbBsg35aMBFvnqONNvcPEuOky+c IBcZX+v+isE2A== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1u4WjU-00000002FHJ-40Fa; Tue, 15 Apr 2025 11:13:08 +0800 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , linux-kernel@vger.kernel.org Subject: [PATCH 3/4] scripts:kdoc_files.py: use glob for export_file seek Date: Tue, 15 Apr 2025 11:12:50 +0800 Message-ID: <21657afdd4f8effe0752a5ec258d74b8a4101f55.1744685912.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.0 In-Reply-To: References: 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 Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" As filenames are expanded using kernel-doc glob, just in case, use it also when checking for exported symbols. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_files.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index 2e51e5f3bb77..630aa5ca6460 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -250,6 +250,8 @@ class KernelFiles(): if not filenames: filenames =3D sorted(self.results.keys()) =20 + glob =3D GlobSourceFiles(srctree=3Dself.config.src_tree) + for fname in filenames: function_table =3D set() =20 @@ -257,7 +259,7 @@ class KernelFiles(): if not export_file: export_file =3D [fname] =20 - for f in export_file: + for f in glob.parse_files(export_file, self.file_not_found= _cb): function_table |=3D self.export_table[f] =20 if symbol: --=20 2.49.0 From nobody Fri Dec 19 16:00:45 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 B3153214A66; Tue, 15 Apr 2025 03:13:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; cv=none; b=IXKfmBkQv7Rtc9o7OhigqTfNSVI5f/eJHMBOcRnBOfVOIOKs5kjrvFpm/9+rJYSLwBLXSV8BhD1Y1OAYoYIePR7oiYInHkybFvk9OZ77L/qBPKB+t19olSDB7xgPCk1ZlvpQkD06zgVtcVXGMFFF6rPC+Uhz5KCoagRFJ0lModQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744686800; c=relaxed/simple; bh=84TV8R3IieGefza5TyZDGmhvzQadd2Ku2wFM7dif50w=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=RqDvxcKLwFdHDqqfdCV38hQjzj2Uzg8d4jk5CjJskihfQsvJu98oBlXqQn4IYt8oPhwcHr6mo9jXBct9A4n5JC5kDPeL8ZfU5MmwIwrNB8kAwAq8vbw2cU0p5PHWumKANhqa3iWuIizvpYwPLxWceZ7ta5PijEO2XOnqs39LXpg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=bzRLTkGH; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="bzRLTkGH" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BB6CBC4CEEA; Tue, 15 Apr 2025 03:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1744686800; bh=84TV8R3IieGefza5TyZDGmhvzQadd2Ku2wFM7dif50w=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bzRLTkGHBzcUfVdrs1ThBYQvMnBb+hCPMCYFM5XfG0Gqukmj3zOwdQRFirj57NTtD H7DWBmUlfikKz90VQ2wLiuu0rUhe7t3u5/PvW9nQhyHh75wBYfaBgbnKjN2HUX+tF7 iVf1O7XxcimNAARHhUETW9VTo9b5QGsAID/q9wshlNDN6nyKMf+Gy3M2YmVGc20Ehy eYul/kHRb68zy41W2cZgHf+7UCAyBndmP0U8cbE+76T9/i+nzPTWLo2jua6pUVsMhP CFyjBDNvCqw5czlLUCfz+n5lLziuZAq1p0iMLE5iPqbj0elvmjIN3n1LqJIxcZArG8 aoE46KwbnkMuQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1u4WjU-00000002FHM-45hG; Tue, 15 Apr 2025 11:13:08 +0800 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , Kees Cook , linux-kernel@vger.kernel.org Subject: [PATCH 4/4] docs: sphinx: kerneldoc: Use python class if available Date: Tue, 15 Apr 2025 11:12:51 +0800 Message-ID: <1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.0 In-Reply-To: References: 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 Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Better integrate with the new kernel-doc tool by calling the Python classes directly if KERNELDOC=3Dscripts/kernel-doc.py. This way, warnings won't be duplicated anymore, as files will be parsed only once. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/kerneldoc.py | 138 ++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 8 deletions(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index 344789ed9ea2..27baf28fb754 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -41,7 +41,14 @@ import sphinx from sphinx.util.docutils import switch_source_input from sphinx.util import logging =20 +srctree =3D os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "scripts/lib/kdoc")) + +from kdoc_files import KernelFiles +from kdoc_output import RestFormat + __version__ =3D '1.0' +use_kfiles =3D False =20 def cmd_str(cmd): """ @@ -82,11 +89,32 @@ class KernelDocDirective(Directive): logger =3D logging.getLogger('kerneldoc') verbose =3D 0 =20 - def run(self): + parse_args =3D {} + msg_args =3D {} + + def handle_args(self): + env =3D self.state.document.settings.env cmd =3D [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] =20 filename =3D env.config.kerneldoc_srctree + '/' + self.arguments[0] + + # Arguments used by KernelFiles.parse() function + self.parse_args =3D { + "file_list": [filename], + "export_file": [] + } + + # Arguments used by KernelFiles.msg() function + self.msg_args =3D { + "enable_lineno": True, + "export": False, + "internal": False, + "symbol": [], + "nosymbol": [], + "no_doc_sections": False + } + export_file_patterns =3D [] =20 verbose =3D os.environ.get("V") @@ -99,7 +127,8 @@ class KernelDocDirective(Directive): # Tell sphinx of the dependency env.note_dependency(os.path.abspath(filename)) =20 - tab_width =3D self.options.get('tab-width', self.state.document.se= ttings.tab_width) + self.tab_width =3D self.options.get('tab-width', + self.state.document.settings.tab= _width) =20 # 'function' is an alias of 'identifiers' if 'functions' in self.options: @@ -108,12 +137,16 @@ class KernelDocDirective(Directive): # FIXME: make this nicer and more robust against errors if 'export' in self.options: cmd +=3D ['-export'] + self.msg_args["export"] =3D True export_file_patterns =3D str(self.options.get('export')).split= () elif 'internal' in self.options: cmd +=3D ['-internal'] + self.msg_args["internal"] =3D True export_file_patterns =3D str(self.options.get('internal')).spl= it() elif 'doc' in self.options: - cmd +=3D ['-function', str(self.options.get('doc'))] + func =3D str(self.options.get('doc')) + cmd +=3D ['-function', func] + self.msg_args["symbol"].append(func) elif 'identifiers' in self.options: identifiers =3D self.options.get('identifiers').split() if identifiers: @@ -123,8 +156,10 @@ class KernelDocDirective(Directive): continue =20 cmd +=3D ['-function', i] + self.msg_args["symbol"].append(i) else: cmd +=3D ['-no-doc-sections'] + self.msg_args["no_doc_sections"] =3D True =20 if 'no-identifiers' in self.options: no_identifiers =3D self.options.get('no-identifiers').split() @@ -135,6 +170,7 @@ class KernelDocDirective(Directive): continue =20 cmd +=3D ['-nosymbol', i] + self.msg_args["nosymbol"].append(i) =20 for pattern in export_file_patterns: pattern =3D pattern.rstrip("\\").strip() @@ -144,12 +180,29 @@ class KernelDocDirective(Directive): for f in glob.glob(env.config.kerneldoc_srctree + '/' + patter= n): env.note_dependency(os.path.abspath(f)) cmd +=3D ['-export-file', f] + self.parse_args["export_file"].append(f) + + # Export file is needed by both parse and msg, as kernel-doc + # cache exports. + self.msg_args["export_file"] =3D self.parse_args["export_file"] =20 cmd +=3D [filename] =20 + return cmd + + def run_cmd(self): + """ + Execute an external kernel-doc command. + """ + + env =3D self.state.document.settings.env + cmd =3D self.handle_args() + if self.verbose >=3D 1: print(cmd_str(cmd)) =20 + node =3D nodes.section() + try: self.logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd)= )) =20 @@ -167,7 +220,29 @@ class KernelDocDirective(Directive): elif env.config.kerneldoc_verbosity > 0: sys.stderr.write(err) =20 - lines =3D statemachine.string2lines(out, tab_width, convert_wh= itespace=3DTrue) + except Exception as e: # pylint: disable=3DW0703 + self.logger.warning("kernel-doc '%s' processing failed with: %= s" % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] + + filenames =3D self.parse_args["file_list"] + for filename in filenames: + ret =3D self.parse_msg(filename, node, out, cmd) + if ret: + return ret + + return node.children + + def parse_msg(self, filename, node, out, cmd): + """ + Handles a kernel-doc output for a given file + """ + + env =3D self.state.document.settings.env + + try: + lines =3D statemachine.string2lines(out, self.tab_width, + convert_whitespace=3DTrue) result =3D ViewList() =20 lineoffset =3D 0; @@ -183,20 +258,65 @@ class KernelDocDirective(Directive): result.append(line, doc + ": " + filename, lineoffset) lineoffset +=3D 1 =20 - node =3D nodes.section() self.do_parse(result, node) =20 - return node.children - except Exception as e: # pylint: disable=3DW0703 self.logger.warning("kernel-doc '%s' processing failed with: %= s" % - (" ".join(cmd), str(e))) + (cmd_str(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] =20 + return None + + def run_kdoc(self, kfiles): + """ + Execute kernel-doc classes directly instead of running as a separa= te + command. + """ + + cmd =3D self.handle_args() + env =3D self.state.document.settings.env + + node =3D nodes.section() + + kfiles.parse(**self.parse_args) + filenames =3D self.parse_args["file_list"] + + for filename, out in kfiles.msg(**self.msg_args, filenames=3Dfilen= ames): + if self.verbose >=3D 1: + print(cmd_str(cmd)) + + ret =3D self.parse_msg(filename, node, out, cmd) + if ret: + return ret + + return node.children + + def run(self): + global use_kfiles + + if use_kfiles: + out_style =3D RestFormat() + kfiles =3D KernelFiles(out_style=3Dout_style, logger=3Dself.lo= gger) + return self.run_kdoc(kfiles) + else: + return self.run_cmd() + def do_parse(self, result, node): with switch_source_input(self.state, result): self.state.nested_parse(result, 0, node, match_titles=3D1) =20 +def setup_kfiles(app): + global use_kfiles + + kerneldoc_bin =3D app.env.config.kerneldoc_bin + + if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"): + print("Using Python kernel-doc") + use_kfiles =3D True + else: + print(f"Using {kerneldoc_bin}") + + def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') @@ -204,6 +324,8 @@ def setup(app): =20 app.add_directive('kernel-doc', KernelDocDirective) =20 + app.connect('builder-inited', setup_kfiles) + return dict( version =3D __version__, parallel_read_safe =3D True, --=20 2.49.0