docs: kdoc: parse_data_structs: Improve docstrings and comments

+39 -23

1 changed file

expand all

tools

lib

python

kdoc

parse_data_structs.py

+39 -23

tools/lib/python/kdoc/parse_data_structs.py

··· 9 9 It accepts an optional file to change the default symbol reference or to 10 10 suppress symbols from the output. 11 11 12 - It is capable of identifying defines, functions, structs, typedefs, 13 - enums and enum symbols and create cross-references for all of them. 12 + It is capable of identifying ``define``, function, ``struct``, ``typedef``, 13 + ``enum`` and ``enum`` symbols and create cross-references for all of them. 14 14 It is also capable of distinguish #define used for specifying a Linux 15 15 ioctl. 16 16 17 - The optional rules file contains a set of rules like: 17 + The optional rules file contains a set of rules like:: 18 18 19 19 ignore ioctl VIDIOC_ENUM_FMT 20 20 replace ioctl VIDIOC_DQBUF vidioc_qbuf ··· 34 34 It is meant to allow having a more comprehensive documentation, where 35 35 uAPI headers will create cross-reference links to the code. 36 36 37 - It is capable of identifying defines, functions, structs, typedefs, 38 - enums and enum symbols and create cross-references for all of them. 37 + It is capable of identifying ``define``, function, ``struct``, ``typedef``, 38 + ``enum`` and ``enum`` symbols and create cross-references for all of them. 39 39 It is also capable of distinguish #define used for specifying a Linux 40 40 ioctl. 41 41 ··· 43 43 allows parsing an exception file. Such file contains a set of rules 44 44 using the syntax below: 45 45 46 - 1. Ignore rules: 46 + 1. Ignore rules:: 47 47 48 48 ignore <type> <symbol>` 49 49 50 50 Removes the symbol from reference generation. 51 51 52 - 2. Replace rules: 52 + 2. Replace rules:: 53 53 54 54 replace <type> <old_symbol> <new_reference> 55 55 ··· 58 58 - A simple symbol name; 59 59 - A full Sphinx reference. 60 60 61 - 3. Namespace rules 61 + 3. Namespace rules:: 62 62 63 63 namespace <namespace> 64 64 65 65 Sets C namespace to be used during cross-reference generation. Can 66 66 be overridden by replace rules. 67 67 68 - On ignore and replace rules, <type> can be: 69 - - ioctl: for defines that end with _IO*, e.g. ioctl definitions 70 - - define: for other defines 71 - - symbol: for symbols defined within enums; 72 - - typedef: for typedefs; 73 - - enum: for the name of a non-anonymous enum; 74 - - struct: for structs. 68 + On ignore and replace rules, ``<type>`` can be: 69 + - ``ioctl``: for defines that end with ``_IO*``, e.g. ioctl definitions 70 + - ``define``: for other defines 71 + - ``symbol``: for symbols defined within enums; 72 + - ``typedef``: for typedefs; 73 + - ``enum``: for the name of a non-anonymous enum; 74 + - ``struct``: for structs. 75 75 76 - Examples: 76 + Examples:: 77 77 78 78 ignore define __LINUX_MEDIA_H 79 79 ignore ioctl VIDIOC_ENUM_FMT ··· 83 83 namespace MC 84 84 """ 85 85 86 - # Parser regexes with multiple ways to capture enums and structs 86 + #: Parser regex with multiple ways to capture enums. 87 87 RE_ENUMS = [ 88 88 re.compile(r"^\s*enum\s+([\w_]+)\s*\{"), 89 89 re.compile(r"^\s*enum\s+([\w_]+)\s*$"), 90 90 re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*\{"), 91 91 re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*$"), 92 92 ] 93 + 94 + #: Parser regex with multiple ways to capture structs. 93 95 RE_STRUCTS = [ 94 96 re.compile(r"^\s*struct\s+([_\w][\w\d_]+)\s*\{"), 95 97 re.compile(r"^\s*struct\s+([_\w][\w\d_]+)$"), ··· 99 97 re.compile(r"^\s*typedef\s*struct\s+([_\w][\w\d_]+)$"), 100 98 ] 101 99 102 - # FIXME: the original code was written a long time before Sphinx C 100 + # NOTE: the original code was written a long time before Sphinx C 103 101 # domain to have multiple namespaces. To avoid to much turn at the 104 102 # existing hyperlinks, the code kept using "c:type" instead of the 105 103 # right types. To change that, we need to change the types not only 106 104 # here, but also at the uAPI media documentation. 105 + 106 + #: Dictionary containing C type identifiers to be transformed. 107 107 DEF_SYMBOL_TYPES = { 108 108 "ioctl": { 109 109 "prefix": "\\ ", ··· 162 158 self.symbols[symbol_type] = {} 163 159 164 160 def read_exceptions(self, fname: str): 161 + """ 162 + Read an optional exceptions file, used to override defaults. 163 + """ 164 + 165 165 if not fname: 166 166 return 167 167 ··· 250 242 def store_type(self, ln, symbol_type: str, symbol: str, 251 243 ref_name: str = None, replace_underscores: bool = True): 252 244 """ 253 - Stores a new symbol at self.symbols under symbol_type. 245 + Store a new symbol at self.symbols under symbol_type. 254 246 255 - By default, underscores are replaced by "-" 247 + By default, underscores are replaced by ``-``. 256 248 """ 257 249 defs = self.DEF_SYMBOL_TYPES[symbol_type] 258 250 ··· 284 276 self.symbols[symbol_type][symbol] = (f"{prefix}{ref_link}{suffix}", ln) 285 277 286 278 def store_line(self, line): 287 - """Stores a line at self.data, properly indented""" 279 + """ 280 + Store a line at self.data, properly indented. 281 + """ 288 282 line = " " + line.expandtabs() 289 283 self.data += line.rstrip(" ") 290 284 291 285 def parse_file(self, file_in: str, exceptions: str = None): 292 - """Reads a C source file and get identifiers""" 286 + """ 287 + Read a C source file and get identifiers. 288 + """ 293 289 self.data = "" 294 290 is_enum = False 295 291 is_comment = False ··· 445 433 446 434 def gen_toc(self): 447 435 """ 448 - Create a list of symbols to be part of a TOC contents table 436 + Create a list of symbols to be part of a TOC contents table. 449 437 """ 450 438 text = [] 451 439 ··· 476 464 return "\n".join(text) 477 465 478 466 def write_output(self, file_in: str, file_out: str, toc: bool): 467 + """ 468 + Write a ReST output file. 469 + """ 470 + 479 471 title = os.path.basename(file_in) 480 472 481 473 if toc:

Configure Feed

Configure Feed