From nobody Fri Dec 19 17:37:42 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