docs: kdoc_parser: Improve docstrings and comments

+92 -77

1 changed file

expand all

tools

lib

python

kdoc

kdoc_parser.py

+92 -77

tools/lib/python/kdoc/kdoc_parser.py

··· 5 5 # pylint: disable=C0301,C0302,R0904,R0912,R0913,R0914,R0915,R0917,R1702 6 6 7 7 """ 8 - kdoc_parser 9 - =========== 10 - 11 - Read a C language source or header FILE and extract embedded 12 - documentation comments 8 + Classes and functions related to reading a C language source or header FILE 9 + and extract embedded documentation comments from it. 13 10 """ 14 11 15 12 import sys ··· 192 195 ] 193 196 194 197 # 195 - # Apply a set of transforms to a block of text. 198 + # Ancillary functions 196 199 # 200 + 197 201 def apply_transforms(xforms, text): 202 + """ 203 + Apply a set of transforms to a block of text. 204 + """ 198 205 for search, subst in xforms: 199 206 text = search.sub(subst, text) 200 207 return text 201 208 202 - # 203 - # A little helper to get rid of excess white space 204 - # 205 209 multi_space = KernRe(r'\s\s+') 206 210 def trim_whitespace(s): 211 + """ 212 + A little helper to get rid of excess white space. 213 + """ 207 214 return multi_space.sub(' ', s.strip()) 208 215 209 - # 210 - # Remove struct/enum members that have been marked "private". 211 - # 212 216 def trim_private_members(text): 213 - # 217 + """ 218 + Remove ``struct``/``enum`` members that have been marked "private". 219 + """ 214 220 # First look for a "public:" block that ends a private region, then 215 221 # handle the "private until the end" case. 216 222 # ··· 226 226 227 227 class state: 228 228 """ 229 - State machine enums 229 + States used by the parser's state machine. 230 230 """ 231 231 232 232 # Parser states 233 - NORMAL = 0 # normal code 234 - NAME = 1 # looking for function name 235 - DECLARATION = 2 # We have seen a declaration which might not be done 236 - BODY = 3 # the body of the comment 237 - SPECIAL_SECTION = 4 # doc section ending with a blank line 238 - PROTO = 5 # scanning prototype 239 - DOCBLOCK = 6 # documentation block 240 - INLINE_NAME = 7 # gathering doc outside main block 241 - INLINE_TEXT = 8 # reading the body of inline docs 233 + NORMAL = 0 #: Normal code. 234 + NAME = 1 #: Looking for function name. 235 + DECLARATION = 2 #: We have seen a declaration which might not be done. 236 + BODY = 3 #: The body of the comment. 237 + SPECIAL_SECTION = 4 #: Doc section ending with a blank line. 238 + PROTO = 5 #: Scanning prototype. 239 + DOCBLOCK = 6 #: Documentation block. 240 + INLINE_NAME = 7 #: Gathering doc outside main block. 241 + INLINE_TEXT = 8 #: Reading the body of inline docs. 242 242 243 + #: Names for each parser state. 243 244 name = [ 244 245 "NORMAL", 245 246 "NAME", ··· 254 253 ] 255 254 256 255 257 - SECTION_DEFAULT = "Description" # default section 256 + SECTION_DEFAULT = "Description" #: Default section. 258 257 259 258 class KernelEntry: 259 + """ 260 + Encapsulates a Kernel documentation entry. 261 + """ 260 262 261 263 def __init__(self, config, fname, ln): 262 264 self.config = config ··· 292 288 # Management of section contents 293 289 # 294 290 def add_text(self, text): 291 + """Add a new text to the entry contents list.""" 295 292 self._contents.append(text) 296 293 297 294 def contents(self): 295 + """Returns a string with all content texts that were added.""" 298 296 return '\n'.join(self._contents) + '\n' 299 297 300 298 # TODO: rename to emit_message after removal of kernel-doc.pl ··· 315 309 self.warnings.append(log_msg) 316 310 return 317 311 318 - # 319 - # Begin a new section. 320 - # 321 312 def begin_section(self, line_no, title = SECTION_DEFAULT, dump = False): 313 + """ 314 + Begin a new section. 315 + """ 322 316 if dump: 323 317 self.dump_section(start_new = True) 324 318 self.section = title ··· 372 366 documentation comments. 373 367 """ 374 368 375 - # Section names 376 - 369 + #: Name of context section. 377 370 section_context = "Context" 371 + 372 + #: Name of return section. 378 373 section_return = "Return" 379 374 375 + #: String to write when a parameter is not described. 380 376 undescribed = "-- undescribed --" 381 377 382 378 def __init__(self, config, fname): ··· 424 416 425 417 def dump_section(self, start_new=True): 426 418 """ 427 - Dumps section contents to arrays/hashes intended for that purpose. 419 + Dump section contents to arrays/hashes intended for that purpose. 428 420 """ 429 421 430 422 if self.entry: ··· 433 425 # TODO: rename it to store_declaration after removal of kernel-doc.pl 434 426 def output_declaration(self, dtype, name, **args): 435 427 """ 436 - Stores the entry into an entry array. 428 + Store the entry into an entry array. 437 429 438 - The actual output and output filters will be handled elsewhere 430 + The actual output and output filters will be handled elsewhere. 439 431 """ 440 432 441 433 item = KdocItem(name, self.fname, dtype, ··· 671 663 self.emit_msg(ln, 672 664 f"No description found for return value of '{declaration_name}'") 673 665 674 - # 675 - # Split apart a structure prototype; returns (struct|union, name, members) or None 676 - # 677 666 def split_struct_proto(self, proto): 667 + """ 668 + Split apart a structure prototype; returns (struct|union, name, 669 + members) or ``None``. 670 + """ 671 + 678 672 type_pattern = r'(struct|union)' 679 673 qualifiers = [ 680 674 "__attribute__", ··· 695 685 if r.search(proto): 696 686 return (r.group(1), r.group(3), r.group(2)) 697 687 return None 698 - # 699 - # Rewrite the members of a structure or union for easier formatting later on. 700 - # Among other things, this function will turn a member like: 701 - # 702 - # struct { inner_members; } foo; 703 - # 704 - # into: 705 - # 706 - # struct foo; inner_members; 707 - # 688 + 708 689 def rewrite_struct_members(self, members): 690 + """ 691 + Process ``struct``/``union`` members from the most deeply nested 692 + outward. 693 + 694 + Rewrite the members of a ``struct`` or ``union`` for easier formatting 695 + later on. Among other things, this function will turn a member like:: 696 + 697 + struct { inner_members; } foo; 698 + 699 + into:: 700 + 701 + struct foo; inner_members; 702 + """ 703 + 709 704 # 710 - # Process struct/union members from the most deeply nested outward. The 711 - # trick is in the ^{ below - it prevents a match of an outer struct/union 712 - # until the inner one has been munged (removing the "{" in the process). 705 + # The trick is in the ``^{`` below - it prevents a match of an outer 706 + # ``struct``/``union`` until the inner one has been munged 707 + # (removing the ``{`` in the process). 713 708 # 714 709 struct_members = KernRe(r'(struct|union)' # 0: declaration type 715 710 r'([^\{\};]+)' # 1: possible name ··· 792 777 tuples = struct_members.findall(members) 793 778 return members 794 779 795 - # 796 - # Format the struct declaration into a standard form for inclusion in the 797 - # resulting docs. 798 - # 799 780 def format_struct_decl(self, declaration): 781 + """ 782 + Format the ``struct`` declaration into a standard form for inclusion 783 + in the resulting docs. 784 + """ 785 + 800 786 # 801 787 # Insert newlines, get rid of extra spaces. 802 788 # ··· 831 815 832 816 def dump_struct(self, ln, proto): 833 817 """ 834 - Store an entry for a struct or union 818 + Store an entry for a ``struct`` or ``union`` 835 819 """ 836 820 # 837 821 # Do the basic parse to get the pieces of the declaration. ··· 873 857 874 858 def dump_enum(self, ln, proto): 875 859 """ 876 - Stores an enum inside self.entries array. 860 + Store an ``enum`` inside self.entries array. 877 861 """ 878 862 # 879 863 # Strip preprocessor directives. Note that this depends on the ··· 1020 1004 1021 1005 def dump_declaration(self, ln, prototype): 1022 1006 """ 1023 - Stores a data declaration inside self.entries array. 1007 + Store a data declaration inside self.entries array. 1024 1008 """ 1025 1009 1026 1010 if self.entry.decl_type == "enum": ··· 1037 1021 1038 1022 def dump_function(self, ln, prototype): 1039 1023 """ 1040 - Stores a function or function macro inside self.entries array. 1024 + Store a function or function macro inside self.entries array. 1041 1025 """ 1042 1026 1043 1027 found = func_macro = False ··· 1138 1122 1139 1123 def dump_typedef(self, ln, proto): 1140 1124 """ 1141 - Stores a typedef inside self.entries array. 1125 + Store a ``typedef`` inside self.entries array. 1142 1126 """ 1143 1127 # 1144 1128 # We start by looking for function typedefs. ··· 1192 1176 @staticmethod 1193 1177 def process_export(function_set, line): 1194 1178 """ 1195 - process EXPORT_SYMBOL* tags 1179 + process ``EXPORT_SYMBOL*`` tags 1196 1180 1197 1181 This method doesn't use any variable from the class, so declare it 1198 1182 with a staticmethod decorator. ··· 1223 1207 1224 1208 def process_normal(self, ln, line): 1225 1209 """ 1226 - STATE_NORMAL: looking for the /** to begin everything. 1210 + STATE_NORMAL: looking for the ``/**`` to begin everything. 1227 1211 """ 1228 1212 1229 1213 if not doc_start.match(line): ··· 1313 1297 else: 1314 1298 self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") 1315 1299 1316 - # 1317 - # Helper function to determine if a new section is being started. 1318 - # 1319 1300 def is_new_section(self, ln, line): 1301 + """ 1302 + Helper function to determine if a new section is being started. 1303 + """ 1320 1304 if doc_sect.search(line): 1321 1305 self.state = state.BODY 1322 1306 # ··· 1348 1332 return True 1349 1333 return False 1350 1334 1351 - # 1352 - # Helper function to detect (and effect) the end of a kerneldoc comment. 1353 - # 1354 1335 def is_comment_end(self, ln, line): 1336 + """ 1337 + Helper function to detect (and effect) the end of a kerneldoc comment. 1338 + """ 1355 1339 if doc_end.search(line): 1356 1340 self.dump_section() 1357 1341 ··· 1370 1354 1371 1355 def process_decl(self, ln, line): 1372 1356 """ 1373 - STATE_DECLARATION: We've seen the beginning of a declaration 1357 + STATE_DECLARATION: We've seen the beginning of a declaration. 1374 1358 """ 1375 1359 if self.is_new_section(ln, line) or self.is_comment_end(ln, line): 1376 1360 return ··· 1399 1383 1400 1384 def process_special(self, ln, line): 1401 1385 """ 1402 - STATE_SPECIAL_SECTION: a section ending with a blank line 1386 + STATE_SPECIAL_SECTION: a section ending with a blank line. 1403 1387 """ 1404 1388 # 1405 1389 # If we have hit a blank line (only the " * " marker), then this ··· 1489 1473 1490 1474 def syscall_munge(self, ln, proto): # pylint: disable=W0613 1491 1475 """ 1492 - Handle syscall definitions 1476 + Handle syscall definitions. 1493 1477 """ 1494 1478 1495 1479 is_void = False ··· 1528 1512 1529 1513 def tracepoint_munge(self, ln, proto): 1530 1514 """ 1531 - Handle tracepoint definitions 1515 + Handle tracepoint definitions. 1532 1516 """ 1533 1517 1534 1518 tracepointname = None ··· 1564 1548 return proto 1565 1549 1566 1550 def process_proto_function(self, ln, line): 1567 - """Ancillary routine to process a function prototype""" 1551 + """Ancillary routine to process a function prototype.""" 1568 1552 1569 1553 # strip C99-style comments to end of line 1570 1554 line = KernRe(r"//.*$", re.S).sub('', line) ··· 1609 1593 self.reset_state(ln) 1610 1594 1611 1595 def process_proto_type(self, ln, line): 1612 - """Ancillary routine to process a type""" 1596 + """ 1597 + Ancillary routine to process a type. 1598 + """ 1613 1599 1614 1600 # Strip C99-style comments and surrounding whitespace 1615 1601 line = KernRe(r"//.*$", re.S).sub('', line).strip() ··· 1665 1647 self.process_proto_type(ln, line) 1666 1648 1667 1649 def process_docblock(self, ln, line): 1668 - """STATE_DOCBLOCK: within a DOC: block.""" 1650 + """STATE_DOCBLOCK: within a ``DOC:`` block.""" 1669 1651 1670 1652 if doc_end.search(line): 1671 1653 self.dump_section() ··· 1677 1659 1678 1660 def parse_export(self): 1679 1661 """ 1680 - Parses EXPORT_SYMBOL* macros from a single Kernel source file. 1662 + Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file. 1681 1663 """ 1682 1664 1683 1665 export_table = set() ··· 1694 1676 1695 1677 return export_table 1696 1678 1697 - # 1698 - # The state/action table telling us which function to invoke in 1699 - # each state. 1700 - # 1679 + #: The state/action table telling us which function to invoke in each state. 1701 1680 state_actions = { 1702 1681 state.NORMAL: process_normal, 1703 1682 state.NAME: process_name,

Configure Feed

Configure Feed