tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: kdoc: Centralize handling of the item section list

The section list always comes directly from the under-construction entry
and is used uniformly. Formalize section handling in the KdocItem class,
and have output_declaration() load the sections directly from the entry,
eliminating a lot of duplicated, verbose parameters.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Jonathan Corbet 8d733875 8d9d1229

+25 -40
+9
scripts/lib/kdoc/kdoc_item.py
··· 9 9 self.name = name 10 10 self.type = type 11 11 self.declaration_start_line = start_line 12 + self.sections = {} 13 + self.sections_start_lines = {} 12 14 # 13 15 # Just save everything else into our own dict so that the output 14 16 # side can grab it directly as before. As we move things into more ··· 26 24 27 25 def __getitem__(self, key): 28 26 return self.get(key) 27 + 28 + # 29 + # Tracking of section information. 30 + # 31 + def set_sections(self, sections, start_lines): 32 + self.sections = sections 33 + self.section_start_lines = start_lines
+13 -23
scripts/lib/kdoc/kdoc_output.py
··· 338 338 starts by putting out the name of the doc section itself, but that 339 339 tends to duplicate a header already in the template file. 340 340 """ 341 - 342 - sections = args.get('sections', {}) 343 - section_start_lines = args.get('section_start_lines', {}) 344 - 345 - for section in sections: 341 + for section, text in args.sections.items(): 346 342 # Skip sections that are in the nosymbol_table 347 343 if section in self.nosymbol: 348 344 continue ··· 350 354 else: 351 355 self.data += f'{self.lineprefix}**{section}**\n\n' 352 356 353 - self.print_lineno(section_start_lines.get(section, 0)) 354 - self.output_highlight(sections[section]) 357 + self.print_lineno(args.section_start_lines.get(section, 0)) 358 + self.output_highlight(text) 355 359 self.data += "\n" 356 360 self.data += "\n" 357 361 ··· 631 635 self.data += line + "\n" 632 636 633 637 def out_doc(self, fname, name, args): 634 - sections = args.get('sections', {}) 635 - 636 638 if not self.check_doc(name, args): 637 639 return 638 640 639 641 self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n" 640 642 641 - for section in sections: 643 + for section, text in args.sections.items(): 642 644 self.data += f'.SH "{section}"' + "\n" 643 - self.output_highlight(sections.get(section)) 645 + self.output_highlight(text) 644 646 645 647 def out_function(self, fname, name, args): 646 648 """output function in man""" 647 649 648 650 parameterlist = args.get('parameterlist', []) 649 651 parameterdescs = args.get('parameterdescs', {}) 650 - sections = args.get('sections', {}) 651 652 652 653 self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" 653 654 ··· 685 692 self.data += f'.IP "{parameter}" 12' + "\n" 686 693 self.output_highlight(parameterdescs.get(parameter_name, "")) 687 694 688 - for section in sections: 695 + for section, text in args.sections.items(): 689 696 self.data += f'.SH "{section.upper()}"' + "\n" 690 - self.output_highlight(sections[section]) 697 + self.output_highlight(text) 691 698 692 699 def out_enum(self, fname, name, args): 693 700 694 701 name = args.get('enum', '') 695 702 parameterlist = args.get('parameterlist', []) 696 - sections = args.get('sections', {}) 697 703 698 704 self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n" 699 705 ··· 719 727 self.data += f'.IP "{parameter}" 12' + "\n" 720 728 self.output_highlight(args['parameterdescs'].get(parameter_name, "")) 721 729 722 - for section in sections: 730 + for section, text in args.sections.items(): 723 731 self.data += f'.SH "{section}"' + "\n" 724 - self.output_highlight(sections[section]) 732 + self.output_highlight(text) 725 733 726 734 def out_typedef(self, fname, name, args): 727 735 module = self.modulename 728 736 typedef = args.get('typedef') 729 737 purpose = args.get('purpose') 730 - sections = args.get('sections', {}) 731 738 732 739 self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n" 733 740 734 741 self.data += ".SH NAME\n" 735 742 self.data += f"typedef {typedef} \\- {purpose}\n" 736 743 737 - for section in sections: 744 + for section, text in args.sections.items(): 738 745 self.data += f'.SH "{section}"' + "\n" 739 - self.output_highlight(sections.get(section)) 746 + self.output_highlight(text) 740 747 741 748 def out_struct(self, fname, name, args): 742 749 module = self.modulename ··· 744 753 purpose = args.get('purpose') 745 754 definition = args.get('definition') 746 755 parameterlist = args.get('parameterlist', []) 747 - sections = args.get('sections', {}) 748 756 parameterdescs = args.get('parameterdescs', {}) 749 757 750 758 self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n" ··· 772 782 self.data += f'.IP "{parameter}" 12' + "\n" 773 783 self.output_highlight(parameterdescs.get(parameter_name)) 774 784 775 - for section in sections: 785 + for section, text in args.sections.items(): 776 786 self.data += f'.SH "{section}"' + "\n" 777 - self.output_highlight(sections.get(section)) 787 + self.output_highlight(text)
+3 -17
scripts/lib/kdoc/kdoc_parser.py
··· 272 272 item = KdocItem(name, dtype, self.entry.declaration_start_line, **args) 273 273 item.warnings = self.entry.warnings 274 274 275 - sections = item.get('sections', {}) 276 - 277 275 # Drop empty sections 278 276 # TODO: improve empty sections logic to emit warnings 277 + sections = self.entry.sections 279 278 for section in ["Description", "Return"]: 280 279 if section in sections and not sections[section].rstrip(): 281 280 del sections[section] 281 + item.set_sections(sections, self.entry.section_start_lines) 282 282 283 283 self.entries.append(item) 284 284 ··· 824 824 parameterdescs=self.entry.parameterdescs, 825 825 parametertypes=self.entry.parametertypes, 826 826 parameterdesc_start_lines=self.entry.parameterdesc_start_lines, 827 - sections=self.entry.sections, 828 - section_start_lines=self.entry.section_start_lines, 829 827 purpose=self.entry.declaration_purpose) 830 828 831 829 def dump_enum(self, ln, proto): ··· 906 908 parameterlist=self.entry.parameterlist, 907 909 parameterdescs=self.entry.parameterdescs, 908 910 parameterdesc_start_lines=self.entry.parameterdesc_start_lines, 909 - sections=self.entry.sections, 910 - section_start_lines=self.entry.section_start_lines, 911 911 purpose=self.entry.declaration_purpose) 912 912 913 913 def dump_declaration(self, ln, prototype): ··· 1075 1079 parameterdescs=self.entry.parameterdescs, 1076 1080 parametertypes=self.entry.parametertypes, 1077 1081 parameterdesc_start_lines=self.entry.parameterdesc_start_lines, 1078 - sections=self.entry.sections, 1079 - section_start_lines=self.entry.section_start_lines, 1080 1082 purpose=self.entry.declaration_purpose, 1081 1083 func_macro=func_macro) 1082 1084 else: ··· 1086 1092 parameterdescs=self.entry.parameterdescs, 1087 1093 parametertypes=self.entry.parametertypes, 1088 1094 parameterdesc_start_lines=self.entry.parameterdesc_start_lines, 1089 - sections=self.entry.sections, 1090 - section_start_lines=self.entry.section_start_lines, 1091 1095 purpose=self.entry.declaration_purpose, 1092 1096 func_macro=func_macro) 1093 1097 ··· 1129 1137 parameterdescs=self.entry.parameterdescs, 1130 1138 parametertypes=self.entry.parametertypes, 1131 1139 parameterdesc_start_lines=self.entry.parameterdesc_start_lines, 1132 - sections=self.entry.sections, 1133 - section_start_lines=self.entry.section_start_lines, 1134 1140 purpose=self.entry.declaration_purpose) 1135 1141 return 1136 1142 ··· 1149 1159 1150 1160 self.output_declaration('typedef', declaration_name, 1151 1161 typedef=declaration_name, 1152 - sections=self.entry.sections, 1153 - section_start_lines=self.entry.section_start_lines, 1154 1162 purpose=self.entry.declaration_purpose) 1155 1163 return 1156 1164 ··· 1630 1642 1631 1643 if doc_end.search(line): 1632 1644 self.dump_section() 1633 - self.output_declaration("doc", self.entry.identifier, 1634 - sections=self.entry.sections, 1635 - section_start_lines=self.entry.section_start_lines) 1645 + self.output_declaration("doc", self.entry.identifier) 1636 1646 self.reset_state(ln) 1637 1647 1638 1648 elif doc_content.search(line):