scripts/kernel-doc.py: adjust some coding style issues

+7 -5

scripts/kernel-doc.py

··· 2 2 # SPDX-License-Identifier: GPL-2.0 3 3 # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>. 4 4 # 5 - # pylint: disable=C0103 5 + # pylint: disable=C0103,R0915 6 6 # 7 7 # Converted from the kernel-doc script originally written in Perl 8 8 # under GPLv2, copyrighted since 1998 by the following authors: ··· 165 165 166 166 167 167 class MsgFormatter(logging.Formatter): 168 + """Helper class to format warnings on a similar way to kernel-doc.pl""" 169 + 168 170 def format(self, record): 169 171 record.levelname = record.levelname.capitalize() 170 172 return logging.Formatter.format(self, record) ··· 243 241 244 242 # Those are valid for all 3 types of filter 245 243 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', 246 - help=NOSYMBOL_DESC) 244 + help=NOSYMBOL_DESC) 247 245 248 246 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", 249 247 action='store_true', help="Don't outputt DOC sections") ··· 288 286 kfiles.parse(args.files, export_file=args.export_file) 289 287 290 288 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 291 - internal=args.internal, symbol=args.symbol, 292 - nosymbol=args.nosymbol, 293 - no_doc_sections=args.no_doc_sections): 289 + internal=args.internal, symbol=args.symbol, 290 + nosymbol=args.nosymbol, 291 + no_doc_sections=args.no_doc_sections): 294 292 msg = t[1] 295 293 if msg: 296 294 print(msg)

+1 -3

scripts/lib/kdoc/kdoc_files.py

··· 4 4 # 5 5 # pylint: disable=R0903,R0913,R0914,R0917 6 6 7 - # TODO: implement warning filtering 8 - 9 7 """ 10 8 Parse lernel-doc tags on multiple kernel source files. 11 9 """ ··· 126 128 def __init__(self, verbose=False, out_style=None, 127 129 werror=False, wreturn=False, wshort_desc=False, 128 130 wcontents_before_sections=False, 129 - logger=None, modulename=None, export_file=None): 131 + logger=None, modulename=None): 130 132 """ 131 133 Initialize startup variables and parse all files 132 134 """

+40 -10

scripts/lib/kdoc/kdoc_output.py

··· 2 2 # SPDX-License-Identifier: GPL-2.0 3 3 # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>. 4 4 # 5 - # pylint: disable=C0301,R0911,R0912,R0913,R0914,R0915,R0917 6 - 7 - # TODO: implement warning filtering 5 + # pylint: disable=C0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917 8 6 9 7 """ 10 8 Implement output filters to print kernel-doc documentation. ··· 50 52 51 53 52 54 class OutputFormat: 55 + """ 56 + Base class for OutputFormat. If used as-is, it means that only 57 + warnings will be displayed. 58 + """ 59 + 53 60 # output mode. 54 61 OUTPUT_ALL = 0 # output all symbols and doc sections 55 62 OUTPUT_INCLUDE = 1 # output only specified symbols ··· 78 75 self.data = "" 79 76 80 77 def set_config(self, config): 78 + """ 79 + Setup global config variables used by both parser and output. 80 + """ 81 + 81 82 self.config = config 82 83 83 84 def set_filter(self, export, internal, symbol, nosymbol, function_table, ··· 124 117 return block 125 118 126 119 def out_warnings(self, args): 120 + """ 121 + Output warnings for identifiers that will be displayed. 122 + """ 123 + 127 124 warnings = args.get('warnings', []) 128 125 129 126 for warning, log_msg in warnings: ··· 157 146 return False 158 147 159 148 def check_declaration(self, dtype, name, args): 149 + """ 150 + Checks if a declaration should be output or not based on the 151 + filtering criteria. 152 + """ 153 + 160 154 if name in self.nosymbol: 161 155 return False 162 156 ··· 185 169 return False 186 170 187 171 def msg(self, fname, name, args): 172 + """ 173 + Handles a single entry from kernel-doc parser 174 + """ 175 + 188 176 self.data = "" 189 177 190 178 dtype = args.get('type', "") ··· 223 203 return None 224 204 225 205 # Virtual methods to be overridden by inherited classes 206 + # At the base class, those do nothing. 226 207 def out_doc(self, fname, name, args): 227 - pass 208 + """Outputs a DOC block""" 228 209 229 210 def out_function(self, fname, name, args): 230 - pass 211 + """Outputs a function""" 231 212 232 213 def out_enum(self, fname, name, args): 233 - pass 214 + """Outputs an enum""" 234 215 235 216 def out_typedef(self, fname, name, args): 236 - pass 217 + """Outputs a typedef""" 237 218 238 219 def out_struct(self, fname, name, args): 239 - pass 220 + """Outputs a struct""" 240 221 241 222 242 223 class RestFormat(OutputFormat): 243 - # """Consts and functions used by ReST output""" 224 + """Consts and functions used by ReST output""" 244 225 245 226 highlights = [ 246 227 (type_constant, r"``\1``"), ··· 286 265 self.data += f".. LINENO {ln}\n" 287 266 288 267 def output_highlight(self, args): 268 + """ 269 + Outputs a C symbol that may require being converted to ReST using 270 + the self.highlights variable 271 + """ 272 + 289 273 input_text = args 290 274 output = "" 291 275 in_literal = False ··· 605 579 self.man_date = dt.strftime("%B %Y") 606 580 607 581 def output_highlight(self, block): 582 + """ 583 + Outputs a C symbol that may require being highlighted with 584 + self.highlights variable using troff syntax 585 + """ 608 586 609 587 contents = self.highlight_block(block) 610 588 ··· 631 601 sections = args.get('sections', {}) 632 602 633 603 if not self.check_doc(name, args): 634 - return 604 + return 635 605 636 606 self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n" 637 607

+7 -23

scripts/lib/kdoc/kdoc_parser.py

··· 131 131 # Place all potential outputs into an array 132 132 self.entries = [] 133 133 134 - # TODO: rename to emit_message 134 + # TODO: rename to emit_message after removal of kernel-doc.pl 135 135 def emit_warning(self, ln, msg, warning=True): 136 136 """Emit a message""" 137 137 ··· 156 156 157 157 name = self.entry.section 158 158 contents = self.entry.contents 159 - 160 - # TODO: we can prevent dumping empty sections here with: 161 - # 162 - # if self.entry.contents.strip("\n"): 163 - # if start_new: 164 - # self.entry.section = self.section_default 165 - # self.entry.contents = "" 166 - # 167 - # return 168 - # 169 - # But, as we want to be producing the same output of the 170 - # venerable kernel-doc Perl tool, let's just output everything, 171 - # at least for now 172 159 173 160 if type_param.match(name): 174 161 name = type_param.group(1) ··· 192 205 self.entry.section = self.section_default 193 206 self.entry.contents = "" 194 207 195 - # TODO: rename it to store_declaration 208 + # TODO: rename it to store_declaration after removal of kernel-doc.pl 196 209 def output_declaration(self, dtype, name, **args): 197 210 """ 198 211 Stores the entry into an entry array. ··· 212 225 args["type"] = dtype 213 226 args["warnings"] = self.entry.warnings 214 227 215 - # TODO: use colletions.OrderedDict 228 + # TODO: use colletions.OrderedDict to remove sectionlist 216 229 217 230 sections = args.get('sections', {}) 218 231 sectionlist = args.get('sectionlist', []) 219 232 220 233 # Drop empty sections 221 - # TODO: improve it to emit warnings 234 + # TODO: improve empty sections logic to emit warnings 222 235 for section in ["Description", "Return"]: 223 236 if section in sectionlist: 224 237 if not sections[section].rstrip(): ··· 623 636 624 637 # Replace macros 625 638 # 626 - # TODO: it is better to also move those to the NestedMatch logic, 639 + # TODO: use NestedMatch for FOO($1, $2, ...) matches 640 + # 641 + # it is better to also move those to the NestedMatch logic, 627 642 # to ensure that parenthesis will be properly matched. 628 643 629 644 (Re(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*$([^$]+)\)', re.S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), ··· 895 906 self.dump_struct(ln, prototype) 896 907 return 897 908 898 - # TODO: handle other types 899 909 self.output_declaration(self.entry.decl_type, prototype, 900 910 entry=self.entry) 901 911 ··· 1667 1679 ln, self.st_name[self.state], 1668 1680 self.st_inline_name[self.inline_doc_state], 1669 1681 line) 1670 - 1671 - # TODO: not all states allow EXPORT_SYMBOL*, so this 1672 - # can be optimized later on to speedup parsing 1673 - self.process_export(self.config.function_table, line) 1674 1682 1675 1683 # Hand this line to the appropriate state handler 1676 1684 if self.state == self.STATE_NORMAL:

+2 -1

scripts/lib/kdoc/kdoc_re.py

··· 131 131 will ignore the search string. 132 132 """ 133 133 134 - # TODO: 134 + # TODO: make NestedMatch handle multiple match groups 135 + # 135 136 # Right now, regular expressions to match it are defined only up to 136 137 # the start delimiter, e.g.: 137 138 #

Configure Feed

Configure Feed