docs: kdoc_output: Improve docstrings and comments

+35 -25

1 changed file

expand all

tools

lib

python

kdoc

kdoc_output.py

+35 -25

tools/lib/python/kdoc/kdoc_output.py

··· 5 5 # pylint: disable=C0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917 6 6 7 7 """ 8 - Implement output filters to print kernel-doc documentation. 8 + Classes to implement output filters to print kernel-doc documentation. 9 9 10 - The implementation uses a virtual base class (OutputFormat) which 10 + The implementation uses a virtual base class ``OutputFormat``. It 11 11 contains dispatches to virtual methods, and some code to filter 12 12 out output messages. 13 13 14 14 The actual implementation is done on one separate class per each type 15 - of output. Currently, there are output classes for ReST and man/troff. 15 + of output, e.g. ``RestFormat`` and ``ManFormat`` classes. 16 + 17 + Currently, there are output classes for ReST and man/troff. 16 18 """ 17 19 18 20 import os ··· 56 54 """ 57 55 58 56 # output mode. 59 - OUTPUT_ALL = 0 # output all symbols and doc sections 60 - OUTPUT_INCLUDE = 1 # output only specified symbols 61 - OUTPUT_EXPORTED = 2 # output exported symbols 62 - OUTPUT_INTERNAL = 3 # output non-exported symbols 57 + OUTPUT_ALL = 0 #: Output all symbols and doc sections. 58 + OUTPUT_INCLUDE = 1 #: Output only specified symbols. 59 + OUTPUT_EXPORTED = 2 #: Output exported symbols. 60 + OUTPUT_INTERNAL = 3 #: Output non-exported symbols. 63 61 64 - # Virtual member to be overridden at the inherited classes 62 + #: Highlights to be used in ReST format. 65 63 highlights = [] 66 64 65 + #: Blank line character. 66 + blankline = "" 67 + 67 68 def __init__(self): 68 - """Declare internal vars and set mode to OUTPUT_ALL""" 69 + """Declare internal vars and set mode to ``OUTPUT_ALL``.""" 69 70 70 71 self.out_mode = self.OUTPUT_ALL 71 72 self.enable_lineno = None ··· 133 128 self.config.warning(log_msg) 134 129 135 130 def check_doc(self, name, args): 136 - """Check if DOC should be output""" 131 + """Check if DOC should be output.""" 137 132 138 133 if self.no_doc_sections: 139 134 return False ··· 182 177 183 178 def msg(self, fname, name, args): 184 179 """ 185 - Handles a single entry from kernel-doc parser 180 + Handles a single entry from kernel-doc parser. 186 181 """ 187 182 188 183 self.data = "" ··· 225 220 # Virtual methods to be overridden by inherited classes 226 221 # At the base class, those do nothing. 227 222 def set_symbols(self, symbols): 228 - """Get a list of all symbols from kernel_doc""" 223 + """Get a list of all symbols from kernel_doc.""" 229 224 230 225 def out_doc(self, fname, name, args): 231 - """Outputs a DOC block""" 226 + """Outputs a DOC block.""" 232 227 233 228 def out_function(self, fname, name, args): 234 - """Outputs a function""" 229 + """Outputs a function.""" 235 230 236 231 def out_enum(self, fname, name, args): 237 - """Outputs an enum""" 232 + """Outputs an enum.""" 238 233 239 234 def out_var(self, fname, name, args): 240 - """Outputs a variable""" 235 + """Outputs a variable.""" 241 236 242 237 def out_typedef(self, fname, name, args): 243 - """Outputs a typedef""" 238 + """Outputs a typedef.""" 244 239 245 240 def out_struct(self, fname, name, args): 246 - """Outputs a struct""" 241 + """Outputs a struct.""" 247 242 248 243 249 244 class RestFormat(OutputFormat): 250 - """Consts and functions used by ReST output""" 245 + """Consts and functions used by ReST output.""" 251 246 247 + #: Highlights to be used in ReST format 252 248 highlights = [ 253 249 (type_constant, r"``\1``"), 254 250 (type_constant2, r"``\1``"), ··· 269 263 (type_fallback, r":c:type:`\1`"), 270 264 (type_param_ref, r"**\1\2**") 271 265 ] 266 + 272 267 blankline = "\n" 273 268 269 + #: Sphinx literal block regex. 274 270 sphinx_literal = KernRe(r'^[^.].*::$', cache=False) 271 + 272 + #: Sphinx code block regex. 275 273 sphinx_cblock = KernRe(r'^\.\.\ +code-block::', cache=False) 276 274 277 275 def __init__(self): ··· 290 280 self.lineprefix = "" 291 281 292 282 def print_lineno(self, ln): 293 - """Outputs a line number""" 283 + """Outputs a line number.""" 294 284 295 285 if self.enable_lineno and ln is not None: 296 286 ln += 1 ··· 299 289 def output_highlight(self, args): 300 290 """ 301 291 Outputs a C symbol that may require being converted to ReST using 302 - the self.highlights variable 292 + the self.highlights variable. 303 293 """ 304 294 305 295 input_text = args ··· 580 570 581 571 582 572 class ManFormat(OutputFormat): 583 - """Consts and functions used by man pages output""" 573 + """Consts and functions used by man pages output.""" 584 574 585 575 highlights = ( 586 576 (type_constant, r"\1"), ··· 597 587 ) 598 588 blankline = "" 599 589 590 + #: Allowed timestamp formats. 600 591 date_formats = [ 601 592 "%a %b %d %H:%M:%S %Z %Y", 602 593 "%a %b %d %H:%M:%S %Y", ··· 664 653 self.symbols = symbols 665 654 666 655 def out_tail(self, fname, name, args): 667 - """Adds a tail for all man pages""" 656 + """Adds a tail for all man pages.""" 668 657 669 658 # SEE ALSO section 670 659 self.data += f'.SH "SEE ALSO"' + "\n.PP\n" ··· 700 689 def output_highlight(self, block): 701 690 """ 702 691 Outputs a C symbol that may require being highlighted with 703 - self.highlights variable using troff syntax 692 + self.highlights variable using troff syntax. 704 693 """ 705 694 706 695 contents = self.highlight_block(block) ··· 731 720 self.output_highlight(text) 732 721 733 722 def out_function(self, fname, name, args): 734 - """output function in man""" 735 723 736 724 out_name = self.arg_name(args, name) 737 725

Configure Feed

Configure Feed