scripts/kernel-doc.py: convert message output to an interactor

+6 -3

scripts/kernel-doc.py

··· 283 283 284 284 kfiles.parse() 285 285 286 - kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 287 - internal=args.internal, symbol=args.symbol, 288 - nosymbol=args.nosymbol) 286 + for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 287 + internal=args.internal, symbol=args.symbol, 288 + nosymbol=args.nosymbol): 289 + msg = t[1] 290 + if msg: 291 + print(msg) 289 292 290 293 291 294 # Call main method

+11 -4

scripts/lib/kdoc/kdoc_files.py

··· 229 229 230 230 def out_msg(self, fname, name, arg): 231 231 """ 232 - Output messages from a file name using the output style filtering. 232 + Return output messages from a file name using the output style 233 + filtering. 233 234 234 - If output type was not handled by the syler, return False. 235 + If output type was not handled by the syler, return None. 235 236 """ 236 237 237 238 # NOTE: we can add rules here to filter out unwanted parts, ··· 243 242 def msg(self, enable_lineno=False, export=False, internal=False, 244 243 symbol=None, nosymbol=None): 245 244 """ 246 - Interacts over the kernel-doc results and output messages. 245 + Interacts over the kernel-doc results and output messages, 246 + returning kernel-doc markups on each interaction 247 247 """ 248 248 249 249 function_table = self.config.function_table ··· 263 261 function_table, enable_lineno) 264 262 265 263 for fname, arg_tuple in self.results: 264 + msg = "" 266 265 for name, arg in arg_tuple: 267 - if self.out_msg(fname, name, arg): 266 + msg += self.out_msg(fname, name, arg) 267 + 268 + if msg is None: 268 269 ln = arg.get("ln", 0) 269 270 dtype = arg.get('type', "") 270 271 271 272 self.config.log.warning("%s:%d Can't handle %s", 272 273 fname, ln, dtype) 274 + if msg: 275 + yield fname, msg

+87 -84

scripts/lib/kdoc/kdoc_output.py

··· 71 71 self.function_table = set() 72 72 self.config = None 73 73 74 + self.data = "" 75 + 74 76 def set_config(self, config): 75 77 self.config = config 76 78 ··· 159 157 return True 160 158 161 159 def msg(self, fname, name, args): 160 + self.data = "" 162 161 163 162 dtype = args.get('type', "") 164 163 165 164 if dtype == "doc": 166 165 self.out_doc(fname, name, args) 167 - return False 166 + return self.data 168 167 169 168 if not self.check_declaration(dtype, name): 170 - return False 169 + return self.data 171 170 172 171 if dtype == "function": 173 172 self.out_function(fname, name, args) 174 - return False 173 + return self.data 175 174 176 175 if dtype == "enum": 177 176 self.out_enum(fname, name, args) 178 - return False 177 + return self.data 179 178 180 179 if dtype == "typedef": 181 180 self.out_typedef(fname, name, args) 182 - return False 181 + return self.data 183 182 184 183 if dtype in ["struct", "union"]: 185 184 self.out_struct(fname, name, args) 186 - return False 185 + return self.data 187 186 188 187 # Warn if some type requires an output logic 189 188 self.config.log.warning("doesn't now how to output '%s' block", 190 189 dtype) 191 190 192 - return True 191 + return None 193 192 194 193 # Virtual methods to be overridden by inherited classes 195 194 def out_doc(self, fname, name, args): ··· 251 248 """Outputs a line number""" 252 249 253 250 if self.enable_lineno and ln: 254 - print(f".. LINENO {ln}") 251 + self.data += f".. LINENO {ln}\n" 255 252 256 253 def output_highlight(self, args): 257 254 input_text = args ··· 298 295 299 296 # Print the output with the line prefix 300 297 for line in output.strip("\n").split("\n"): 301 - print(self.lineprefix + line) 298 + self.data += self.lineprefix + line + "\n" 302 299 303 300 def out_section(self, args, out_reference=False): 304 301 """ ··· 320 317 321 318 if not self.out_mode == self.OUTPUT_INCLUDE: 322 319 if out_reference: 323 - print(f".. _{section}:\n") 320 + self.data += f".. _{section}:\n\n" 324 321 325 322 if not self.symbol: 326 - print(f'{self.lineprefix}**{section}**\n') 323 + self.data += f'{self.lineprefix}**{section}**\n\n' 327 324 328 325 self.print_lineno(section_start_lines.get(section, 0)) 329 326 self.output_highlight(sections[section]) 330 - print() 331 - print() 327 + self.data += "\n" 328 + self.data += "\n" 332 329 333 330 def out_doc(self, fname, name, args): 334 331 if not self.check_doc(name): ··· 371 368 signature += ")" 372 369 373 370 if args.get('typedef') or not args.get('functiontype'): 374 - print(f".. c:macro:: {args['function']}\n") 371 + self.data += f".. c:macro:: {args['function']}\n\n" 375 372 376 373 if args.get('typedef'): 377 374 self.print_lineno(ln) 378 - print(" **Typedef**: ", end="") 375 + self.data += " **Typedef**: " 379 376 self.lineprefix = "" 380 377 self.output_highlight(args.get('purpose', "")) 381 - print("\n\n**Syntax**\n") 382 - print(f" ``{signature}``\n") 378 + self.data += "\n\n**Syntax**\n\n" 379 + self.data += f" ``{signature}``\n\n" 383 380 else: 384 - print(f"``{signature}``\n") 381 + self.data += f"``{signature}``\n\n" 385 382 else: 386 - print(f".. c:function:: {signature}\n") 383 + self.data += f".. c:function:: {signature}\n\n" 387 384 388 385 if not args.get('typedef'): 389 386 self.print_lineno(ln) 390 387 self.lineprefix = " " 391 388 self.output_highlight(args.get('purpose', "")) 392 - print() 389 + self.data += "\n" 393 390 394 391 # Put descriptive text into a container (HTML <div>) to help set 395 392 # function prototypes apart 396 393 self.lineprefix = " " 397 394 398 395 if parameterlist: 399 - print(".. container:: kernelindent\n") 400 - print(f"{self.lineprefix}**Parameters**\n") 396 + self.data += ".. container:: kernelindent\n\n" 397 + self.data += f"{self.lineprefix}**Parameters**\n\n" 401 398 402 399 for parameter in parameterlist: 403 400 parameter_name = Re(r'\[.*').sub('', parameter) 404 401 dtype = args['parametertypes'].get(parameter, "") 405 402 406 403 if dtype: 407 - print(f"{self.lineprefix}``{dtype}``") 404 + self.data += f"{self.lineprefix}``{dtype}``\n" 408 405 else: 409 - print(f"{self.lineprefix}``{parameter}``") 406 + self.data += f"{self.lineprefix}``{parameter}``\n" 410 407 411 408 self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0)) 412 409 ··· 415 412 parameterdescs[parameter_name] != KernelDoc.undescribed: 416 413 417 414 self.output_highlight(parameterdescs[parameter_name]) 418 - print() 415 + self.data += "\n" 419 416 else: 420 - print(f"{self.lineprefix}*undescribed*\n") 417 + self.data += f"{self.lineprefix}*undescribed*\n\n" 421 418 self.lineprefix = " " 422 419 423 420 self.out_section(args) ··· 431 428 parameterdescs = args.get('parameterdescs', {}) 432 429 ln = args.get('ln', 0) 433 430 434 - print(f"\n\n.. c:enum:: {name}\n") 431 + self.data += f"\n\n.. c:enum:: {name}\n\n" 435 432 436 433 self.print_lineno(ln) 437 434 self.lineprefix = " " 438 435 self.output_highlight(args.get('purpose', '')) 439 - print() 436 + self.data += "\n" 440 437 441 - print(".. container:: kernelindent\n") 438 + self.data += ".. container:: kernelindent\n\n" 442 439 outer = self.lineprefix + " " 443 440 self.lineprefix = outer + " " 444 - print(f"{outer}**Constants**\n") 441 + self.data += f"{outer}**Constants**\n\n" 445 442 446 443 for parameter in parameterlist: 447 - print(f"{outer}``{parameter}``") 444 + self.data += f"{outer}``{parameter}``\n" 448 445 449 446 if parameterdescs.get(parameter, '') != KernelDoc.undescribed: 450 447 self.output_highlight(parameterdescs[parameter]) 451 448 else: 452 - print(f"{self.lineprefix}*undescribed*\n") 453 - print() 449 + self.data += f"{self.lineprefix}*undescribed*\n\n" 450 + self.data += "\n" 454 451 455 452 self.lineprefix = oldprefix 456 453 self.out_section(args) ··· 461 458 name = args.get('typedef', '') 462 459 ln = args.get('ln', 0) 463 460 464 - print(f"\n\n.. c:type:: {name}\n") 461 + self.data += f"\n\n.. c:type:: {name}\n\n" 465 462 466 463 self.print_lineno(ln) 467 464 self.lineprefix = " " 468 465 469 466 self.output_highlight(args.get('purpose', '')) 470 467 471 - print() 468 + self.data += "\n" 472 469 473 470 self.lineprefix = oldprefix 474 471 self.out_section(args) ··· 485 482 parameterdescs = args.get('parameterdescs', {}) 486 483 parameterdesc_start_lines = args.get('parameterdesc_start_lines', {}) 487 484 488 - print(f"\n\n.. c:{dtype}:: {name}\n") 485 + self.data += f"\n\n.. c:{dtype}:: {name}\n\n" 489 486 490 487 self.print_lineno(ln) 491 488 ··· 493 490 self.lineprefix += " " 494 491 495 492 self.output_highlight(purpose) 496 - print() 493 + self.data += "\n" 497 494 498 - print(".. container:: kernelindent\n") 499 - print(f"{self.lineprefix}**Definition**::\n") 495 + self.data += ".. container:: kernelindent\n\n" 496 + self.data += f"{self.lineprefix}**Definition**::\n\n" 500 497 501 498 self.lineprefix = self.lineprefix + " " 502 499 503 500 declaration = declaration.replace("\t", self.lineprefix) 504 501 505 - print(f"{self.lineprefix}{dtype} {name}" + ' {') 506 - print(f"{declaration}{self.lineprefix}" + "};\n") 502 + self.data += f"{self.lineprefix}{dtype} {name}" + ' {' + "\n" 503 + self.data += f"{declaration}{self.lineprefix}" + "};\n\n" 507 504 508 505 self.lineprefix = " " 509 - print(f"{self.lineprefix}**Members**\n") 506 + self.data += f"{self.lineprefix}**Members**\n\n" 510 507 for parameter in parameterlist: 511 508 if not parameter or parameter.startswith("#"): 512 509 continue ··· 518 515 519 516 self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0)) 520 517 521 - print(f"{self.lineprefix}``{parameter}``") 518 + self.data += f"{self.lineprefix}``{parameter}``\n" 522 519 523 520 self.lineprefix = " " 524 521 self.output_highlight(parameterdescs[parameter_name]) 525 522 self.lineprefix = " " 526 523 527 - print() 524 + self.data += "\n" 528 525 529 - print() 526 + self.data += "\n" 530 527 531 528 self.lineprefix = oldprefix 532 529 self.out_section(args) ··· 579 576 line = Re(r"^\s*").sub("", line) 580 577 581 578 if line and line[0] == ".": 582 - print("\\&" + line) 579 + self.data += "\\&" + line + "\n" 583 580 else: 584 - print(line) 581 + self.data += line + "\n" 585 582 586 583 def out_doc(self, fname, name, args): 587 584 module = args.get('module') 588 585 sectionlist = args.get('sectionlist', []) 589 586 sections = args.get('sections', {}) 590 587 591 - print(f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX') 588 + self.data += f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual" LINUX' + "\n" 592 589 593 590 for section in sectionlist: 594 - print(f'.SH "{section}"') 591 + self.data += f'.SH "{section}"' + "\n" 595 592 self.output_highlight(sections.get(section)) 596 593 597 594 def out_function(self, fname, name, args): ··· 602 599 sectionlist = args.get('sectionlist', []) 603 600 sections = args.get('sections', {}) 604 601 605 - print(f'.TH "{args['function']}" 9 "{args['function']}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX') 602 + self.data += f'.TH "{args['function']}" 9 "{args['function']}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" 606 603 607 - print(".SH NAME") 608 - print(f"{args['function']} \\- {args['purpose']}") 604 + self.data += ".SH NAME\n" 605 + self.data += f"{args['function']} \\- {args['purpose']}\n" 609 606 610 - print(".SH SYNOPSIS") 607 + self.data += ".SH SYNOPSIS\n" 611 608 if args.get('functiontype', ''): 612 - print(f'.B "{args['functiontype']}" {args['function']}') 609 + self.data += f'.B "{args['functiontype']}" {args['function']}' + "\n" 613 610 else: 614 - print(f'.B "{args['function']}') 611 + self.data += f'.B "{args['function']}' + "\n" 615 612 616 613 count = 0 617 614 parenth = "(" ··· 624 621 dtype = args['parametertypes'].get(parameter, "") 625 622 if function_pointer.match(dtype): 626 623 # Pointer-to-function 627 - print(f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"') 624 + self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n" 628 625 else: 629 626 dtype = Re(r'([^\*])$').sub(r'\1 ', dtype) 630 627 631 - print(f'.BI "{parenth}{dtype}" "{post}"') 628 + self.data += f'.BI "{parenth}{dtype}" "{post}"' + "\n" 632 629 count += 1 633 630 parenth = "" 634 631 635 632 if parameterlist: 636 - print(".SH ARGUMENTS") 633 + self.data += ".SH ARGUMENTS\n" 637 634 638 635 for parameter in parameterlist: 639 636 parameter_name = re.sub(r'\[.*', '', parameter) 640 637 641 - print(f'.IP "{parameter}" 12') 638 + self.data += f'.IP "{parameter}" 12' + "\n" 642 639 self.output_highlight(parameterdescs.get(parameter_name, "")) 643 640 644 641 for section in sectionlist: 645 - print(f'.SH "{section.upper()}"') 642 + self.data += f'.SH "{section.upper()}"' + "\n" 646 643 self.output_highlight(sections[section]) 647 644 648 645 def out_enum(self, fname, name, args): ··· 652 649 sectionlist = args.get('sectionlist', []) 653 650 sections = args.get('sections', {}) 654 651 655 - print(f'.TH "{args['module']}" 9 "enum {args['enum']}" "{self.man_date}" "API Manual" LINUX') 652 + self.data += f'.TH "{args['module']}" 9 "enum {args['enum']}" "{self.man_date}" "API Manual" LINUX' + "\n" 656 653 657 - print(".SH NAME") 658 - print(f"enum {args['enum']} \\- {args['purpose']}") 654 + self.data += ".SH NAME\n" 655 + self.data += f"enum {args['enum']} \\- {args['purpose']}\n" 659 656 660 - print(".SH SYNOPSIS") 661 - print(f"enum {args['enum']}" + " {") 657 + self.data += ".SH SYNOPSIS\n" 658 + self.data += f"enum {args['enum']}" + " {\n" 662 659 663 660 count = 0 664 661 for parameter in parameterlist: 665 - print(f'.br\n.BI " {parameter}"') 662 + self.data += f'.br\n.BI " {parameter}"' + "\n" 666 663 if count == len(parameterlist) - 1: 667 - print("\n};") 664 + self.data += "\n};\n" 668 665 else: 669 - print(", \n.br") 666 + self.data += ", \n.br\n" 670 667 671 668 count += 1 672 669 673 - print(".SH Constants") 670 + self.data += ".SH Constants\n" 674 671 675 672 for parameter in parameterlist: 676 673 parameter_name = Re(r'\[.*').sub('', parameter) 677 - print(f'.IP "{parameter}" 12') 674 + self.data += f'.IP "{parameter}" 12' + "\n" 678 675 self.output_highlight(args['parameterdescs'].get(parameter_name, "")) 679 676 680 677 for section in sectionlist: 681 - print(f'.SH "{section}"') 678 + self.data += f'.SH "{section}"' + "\n" 682 679 self.output_highlight(sections[section]) 683 680 684 681 def out_typedef(self, fname, name, args): ··· 688 685 sectionlist = args.get('sectionlist', []) 689 686 sections = args.get('sections', {}) 690 687 691 - print(f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX') 688 + self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n" 692 689 693 - print(".SH NAME") 694 - print(f"typedef {typedef} \\- {purpose}") 690 + self.data += ".SH NAME\n" 691 + self.data += f"typedef {typedef} \\- {purpose}\n" 695 692 696 693 for section in sectionlist: 697 - print(f'.SH "{section}"') 694 + self.data += f'.SH "{section}"' + "\n" 698 695 self.output_highlight(sections.get(section)) 699 696 700 697 def out_struct(self, fname, name, args): ··· 708 705 sections = args.get('sections', {}) 709 706 parameterdescs = args.get('parameterdescs', {}) 710 707 711 - print(f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX') 708 + self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n" 712 709 713 - print(".SH NAME") 714 - print(f"{struct_type} {struct_name} \\- {purpose}") 710 + self.data += ".SH NAME\n" 711 + self.data += f"{struct_type} {struct_name} \\- {purpose}\n" 715 712 716 713 # Replace tabs with two spaces and handle newlines 717 714 declaration = definition.replace("\t", " ") 718 715 declaration = Re(r"\n").sub('"\n.br\n.BI "', declaration) 719 716 720 - print(".SH SYNOPSIS") 721 - print(f"{struct_type} {struct_name} " + "{" + "\n.br") 722 - print(f'.BI "{declaration}\n' + "};\n.br\n") 717 + self.data += ".SH SYNOPSIS\n" 718 + self.data += f"{struct_type} {struct_name} " + "{" + "\n.br\n" 719 + self.data += f'.BI "{declaration}\n' + "};\n.br\n\n" 723 720 724 - print(".SH Members") 721 + self.data += ".SH Members\n" 725 722 for parameter in parameterlist: 726 723 if parameter.startswith("#"): 727 724 continue ··· 731 728 if parameterdescs.get(parameter_name) == KernelDoc.undescribed: 732 729 continue 733 730 734 - print(f'.IP "{parameter}" 12') 731 + self.data += f'.IP "{parameter}" 12' + "\n" 735 732 self.output_highlight(parameterdescs.get(parameter_name)) 736 733 737 734 for section in sectionlist: 738 - print(f'.SH "{section}"') 735 + self.data += f'.SH "{section}"' + "\n" 739 736 self.output_highlight(sections.get(section))

Configure Feed

Configure Feed