| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <ad841ed077503f790f20fa10e543155d1d1bc1a0.1739972906.git.mchehab+huawei@kernel.org>
Date: Wed, 19 Feb 2025 14:57:37 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
"Mauro Carvalho Chehab" <mchehab+huawei@...nel.org>,
linux-kernel@...r.kernel.org
Subject: [PATCH 2/6] scripts/kernel-doc.py: adjust some coding style issues
Make pylint happier by adding some missing documentation and
addressing a couple of pylint warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
---
scripts/kernel-doc.py | 2 ++
scripts/lib/kdoc/kdoc_files.py | 4 +--
scripts/lib/kdoc/kdoc_output.py | 51 ++++++++++++++++++++++++++-------
3 files changed, 43 insertions(+), 14 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index d700451e9541..daae2b4f3307 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -90,6 +90,8 @@ neither here nor at the original Perl script.
class MsgFormatter(logging.Formatter):
+ """Helper class to format warnings on a similar way to kernel-doc.pl"""
+
def format(self, record):
record.levelname = record.levelname.capitalize()
return logging.Formatter.format(self, record)
diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py
index 957aaeaed7e6..e1ed2f6dae94 100755
--- a/scripts/lib/kdoc/kdoc_files.py
+++ b/scripts/lib/kdoc/kdoc_files.py
@@ -3,8 +3,6 @@
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@...nel.org>.
# SPDX-License-Identifier: GPL-2.0
-# TODO: implement warning filtering
-
"""
Parse lernel-doc tags on multiple kernel source files.
"""
@@ -127,7 +125,7 @@ class KernelFiles():
def __init__(self, verbose=False, out_style=None,
werror=False, wreturn=False, wshort_desc=False,
wcontents_before_sections=False,
- logger=None, modulename=None, export_file=None):
+ logger=None, modulename=None):
"""
Initialize startup variables and parse all files
"""
diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index 7aeaec884545..97ec671e0b6e 100755
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -1,10 +1,8 @@
#!/usr/bin/env python3
-# pylint: disable=C0301,R0911,R0912,R0913,R0914,R0915,R0917
+# pylint: disable=C0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@...nel.org>.
# SPDX-License-Identifier: GPL-2.0
-# TODO: implement warning filtering
-
"""
Implement output filters to print kernel-doc documentation.
@@ -51,6 +49,11 @@ type_member_func = type_member + Re(r"\(\)", cache=False)
class OutputFormat:
+ """
+ Base class for OutputFormat. If used as-is, it means that only
+ warnings will be displayed.
+ """
+
# output mode.
OUTPUT_ALL = 0 # output all symbols and doc sections
OUTPUT_INCLUDE = 1 # output only specified symbols
@@ -74,6 +77,10 @@ class OutputFormat:
self.data = ""
def set_config(self, config):
+ """
+ Setup global config variables used by both parser and output.
+ """
+
self.config = config
def set_filter(self, export, internal, symbol, nosymbol, function_table,
@@ -116,6 +123,10 @@ class OutputFormat:
return block
def out_warnings(self, args):
+ """
+ Output warnings for identifiers that will be displayed.
+ """
+
warnings = args.get('warnings', [])
for warning, log_msg in warnings:
@@ -145,6 +156,11 @@ class OutputFormat:
return False
def check_declaration(self, dtype, name, args):
+ """
+ Checks if a declaration should be output or not based on the
+ filtering criteria.
+ """
+
if name in self.nosymbol:
return False
@@ -168,6 +184,10 @@ class OutputFormat:
return False
def msg(self, fname, name, args):
+ """
+ Handles a single entry from kernel-doc parser
+ """
+
self.data = ""
dtype = args.get('type', "")
@@ -202,24 +222,24 @@ class OutputFormat:
return None
# Virtual methods to be overridden by inherited classes
+ # At the base class, those do nothing.
def out_doc(self, fname, name, args):
- pass
+ """Outputs a DOC block"""
def out_function(self, fname, name, args):
- pass
+ """Outputs a function"""
def out_enum(self, fname, name, args):
- pass
+ """Outputs an enum"""
def out_typedef(self, fname, name, args):
- pass
+ """Outputs a typedef"""
def out_struct(self, fname, name, args):
- pass
-
+ """Outputs a struct"""
class RestFormat(OutputFormat):
- # """Consts and functions used by ReST output"""
+ """Consts and functions used by ReST output"""
highlights = [
(type_constant, r"``\1``"),
@@ -264,6 +284,11 @@ class RestFormat(OutputFormat):
self.data += f".. LINENO {ln}\n"
def output_highlight(self, args):
+ """
+ Outputs a C symbol that may require being converted to ReST using
+ the self.highlights variable
+ """
+
input_text = args
output = ""
in_literal = False
@@ -578,6 +603,10 @@ class ManFormat(OutputFormat):
self.man_date = dt.strftime("%B %Y")
def output_highlight(self, block):
+ """
+ Outputs a C symbol that may require being highlighted with
+ self.highlights variable using troff syntax
+ """
contents = self.highlight_block(block)
@@ -600,7 +629,7 @@ class ManFormat(OutputFormat):
sections = args.get('sections', {})
if not self.check_doc(name, args):
- return
+ return
self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n"
--
2.48.1
Powered by blists - more mailing lists