docs: python: abi_parser: do some improvements at documentation

+18 -15

1 changed file

expand all

tools

lib

python

abi

abi_parser.py

+18 -15

tools/lib/python/abi/abi_parser.py

··· 21 21 22 22 23 23 class AbiParser: 24 - """Main class to parse ABI files""" 24 + """Main class to parse ABI files.""" 25 25 26 + #: Valid tags at Documentation/ABI. 26 27 TAGS = r"(what|where|date|kernelversion|contact|description|users)" 28 + 29 + #: ABI elements that will auto-generate cross-references. 27 30 XREF = r"(?:^|\s|\()(\/(?:sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)(?:[,.:;\)\s]|\Z)" 28 31 29 32 def __init__(self, directory, logger=None, 30 33 enable_lineno=False, show_warnings=True, debug=0): 31 - """Stores arguments for the class and initialize class vars""" 34 + """Stores arguments for the class and initialize class vars.""" 32 35 33 36 self.directory = directory 34 37 self.enable_lineno = enable_lineno ··· 68 65 self.re_xref_node = re.compile(self.XREF) 69 66 70 67 def warn(self, fdata, msg, extra=None): 71 - """Displays a parse error if warning is enabled""" 68 + """Displays a parse error if warning is enabled.""" 72 69 73 70 if not self.show_warnings: 74 71 return ··· 80 77 self.log.warning(msg) 81 78 82 79 def add_symbol(self, what, fname, ln=None, xref=None): 83 - """Create a reference table describing where each 'what' is located""" 80 + """Create a reference table describing where each 'what' is located.""" 84 81 85 82 if what not in self.what_symbols: 86 83 self.what_symbols[what] = {"file": {}} ··· 95 92 self.what_symbols[what]["xref"] = xref 96 93 97 94 def _parse_line(self, fdata, line): 98 - """Parse a single line of an ABI file""" 95 + """Parse a single line of an ABI file.""" 99 96 100 97 new_what = False 101 98 new_tag = False ··· 267 264 self.warn(fdata, "Unexpected content", line) 268 265 269 266 def parse_readme(self, nametag, fname): 270 - """Parse ABI README file""" 267 + """Parse ABI README file.""" 271 268 272 269 nametag["what"] = ["Introduction"] 273 270 nametag["path"] = "README" ··· 285 282 nametag["description"] += line 286 283 287 284 def parse_file(self, fname, path, basename): 288 - """Parse a single file""" 285 + """Parse a single file.""" 289 286 290 287 ref = f"abi_file_{path}_{basename}" 291 288 ref = self.re_unprintable.sub("_", ref).strip("_") ··· 351 348 self.add_symbol(what=w, fname=fname, xref=fdata.key) 352 349 353 350 def _parse_abi(self, root=None): 354 - """Internal function to parse documentation ABI recursively""" 351 + """Internal function to parse documentation ABI recursively.""" 355 352 356 353 if not root: 357 354 root = self.directory ··· 380 377 self.parse_file(name, path, basename) 381 378 382 379 def parse_abi(self, root=None): 383 - """Parse documentation ABI""" 380 + """Parse documentation ABI.""" 384 381 385 382 self._parse_abi(root) 386 383 ··· 388 385 self.log.debug(pformat(self.data)) 389 386 390 387 def desc_txt(self, desc): 391 - """Print description as found inside ABI files""" 388 + """Print description as found inside ABI files.""" 392 389 393 390 desc = desc.strip(" \t\n") 394 391 ··· 396 393 397 394 def xref(self, fname): 398 395 """ 399 - Converts a Documentation/ABI + basename into a ReST cross-reference 396 + Converts a Documentation/ABI + basename into a ReST cross-reference. 400 397 """ 401 398 402 399 xref = self.file_refs.get(fname) ··· 406 403 return xref 407 404 408 405 def desc_rst(self, desc): 409 - """Enrich ReST output by creating cross-references""" 406 + """Enrich ReST output by creating cross-references.""" 410 407 411 408 # Remove title markups from the description 412 409 # Having titles inside ABI files will only work if extra ··· 462 459 463 460 def doc(self, output_in_txt=False, show_symbols=True, show_file=True, 464 461 filter_path=None): 465 - """Print ABI at stdout""" 462 + """Print ABI at stdout.""" 466 463 467 464 part = None 468 465 for key, v in sorted(self.data.items(), ··· 552 549 yield (msg, file_ref[0][0], ln) 553 550 554 551 def check_issues(self): 555 - """Warn about duplicated ABI entries""" 552 + """Warn about duplicated ABI entries.""" 556 553 557 554 for what, v in self.what_symbols.items(): 558 555 files = v.get("file") ··· 578 575 self.log.warning("%s is defined %d times: %s", what, len(f), "; ".join(f)) 579 576 580 577 def search_symbols(self, expr): 581 - """ Searches for ABI symbols """ 578 + """ Searches for ABI symbols.""" 582 579 583 580 regex = re.compile(expr, re.I) 584 581

Configure Feed

Configure Feed