2 # SPDX-License-Identifier: GPL-2.0
22 # Regular expressions used to parse kernel-doc markups at KernelDoc class.
42 #         @{section-name}:
60 type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
70                         r'(\w+)\s*(?:\(\w*\))?\s*' +	# name and optional "(...)"
71                         r'(?:[-:].*)?$',		# description (not captured)
100     NAME          = 1        #: Looking for function name.  variable in state
110     name = [  variable in state
112         "NAME",
127     Encapsulates a Kernel documentation entry.
161         """Add a new text to the entry contents list."""
168     # TODO: rename to emit_message after removal of kernel-doc.pl
203         name = self.section
206         if type_param.match(name):
207             name = type_param.group(1)
209             self.parameterdescs[name] = contents
210             self.parameterdesc_start_lines[name] = self.new_start_line
215             if name in self.sections and self.sections[name] != "":
216                 # Only warn on user-specified duplicate section names
217                 if name != SECTION_DEFAULT:
219                                   f"duplicate section name '{name}'")
220                 # Treat as a new paragraph - add a blank line
221                 self.sections[name] += '\n' + contents
223                 self.sections[name] = contents
224                 self.sections_start_lines[name] = self.new_start_line
227 #        self.config.log.debug("Section: %s : %s", name, pformat(vars(self)))
241     #: Name of context section.
244     #: Name of return section.
248     undescribed = "-- undescribed --"
263         # Store entry currently being processed
264         self.entry = None
284         if self.entry:
285             self.entry.emit_msg(ln, msg, warning=warning)
300         if self.entry:
301             self.entry.dump_section(start_new)
303     # TODO: rename it to store_declaration after removal of kernel-doc.pl
304     def output_declaration(self, dtype, name, **args):  argument
306         Store the entry into an entry array.
311         item = KdocItem(name, self.fname, dtype,
312                         self.entry.declaration_start_line, **args)
313         item.warnings = self.entry.warnings
317         sections = self.entry.sections
321         item.set_sections(sections, self.entry.sections_start_lines)
322         item.set_params(self.entry.parameterlist, self.entry.parameterdescs,
323                         self.entry.parametertypes,
324                         self.entry.parameterdesc_start_lines)
327         self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
331         When the parser fails to produce a valid entry, it places some
332         warnings under `entry.warnings` that will be discarded when resetting
340               warnings are not filtered by the `-W` parameters: they will all
341               be produced even when `-Wreturn`, `-Wshort-desc`, and/or
342               `-Wcontents-before-sections` are used.
349         if self.entry and self.entry not in self.entries:
350             for log_msg in self.entry.warnings:
355         Ancillary routine to create a new entry. It initializes all
361         self.entry = KernelEntry(self.config, self.fname, ln)
369         Store parameters and their descriptions at self.entry.
372         if self.entry.anon_struct_union and dtype == "" and param == "}":
375         self.entry.anon_struct_union = False
385                 if named_variadic: # there is a name provided, use that
388                     # ``@name...:`` form, the description is stored in
392                     # excess-parameter check in check_sections() does
395                     orig = self.entry.parameterdescs.pop(param, None)
396                     param = param[:-3]
398                        not self.entry.parameterdescs.get(param):
399                         self.entry.parameterdescs[param] = orig
400                 if not self.entry.parameterdescs.get(param):
403                     # standard "not described" warning before auto-filling
404                     # so a missing or mistyped ``@<name>:`` doc tag does
406                     # natural name for the user to document and so always
407                     # gets the auto-generated text.
414                     self.entry.parameterdescs[param] = "variable arguments"
418                 self.entry.parameterdescs[param] = "no arguments"
424                 self.entry.parameterdescs[param] = "anonymous\n"
425                 self.entry.anon_struct_union = True
430         if param not in self.entry.parameterdescs and not param.startswith("#"):
431             self.entry.parameterdescs[param] = self.undescribed
450         self.entry.parameterlist.append(param)
452         self.entry.parametertypes[param] = org_arg
458         Creates a list of parameters, storing them at self.entry.
488             # The pointer-to-function case.
493                            r'([\w\[\].]*)'    # Capture the name and possible [array]
503             # The array-of-pointers case.  Dig the parameter name out from the middle
508                            r'([\w.]*?)'			# The actual pointer name
542                     # For pointers, shift the star(s) from the variable name to the
554                         if dtype != "":  # Skip unnamed bit-fields
563         # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
572             final_part = parts[-1]
580         # For decl name 'flgas', suggests 'flags'
583         # For decl name 'member', suggests 'longer_member'
584         full_substrings = [name for name in possible_names if decl_name in name]
612         for section in self.entry.sections:
613             if section not in self.entry.parameterlist and \
615                 hint = self.get_suggestions_hint(section, self.entry.parameterlist)
626         # the declaration.  This catches mismatched or stale kernel-doc
630         for param_name, desc in self.entry.parameterdescs.items():
631             # Skip auto-generated entries from push_parameter()
638             if param_name in self.entry.parameterlist:
641             hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
663         if not self.entry.sections.get("Return", None):
669         Split apart a structure prototype; returns (struct|union, name,
708         # The trick is in the ``^{`` below - it prevents a match of an outer
713                                 r'([^\{\};]+)' 	    # 1: possible name
723                 dtype, name, lbr, content, rbr, rest, semi = t
725                 # Pass through each field name, normalizing the form and formatting.
731                     # Remove bitfield/array/pointer info, getting the bare name.
741                         # Look for (type)(*name)(args) - pointer to function
745                             dtype, name, extra = r.group(1), r.group(2), r.group(3)
746                             # Pointer-to-function
749                                 newmember += f"{dtype}{name}{extra}; "
751                                 newmember += f"{dtype}{s_id}.{name}{extra}; "
753                         # Otherwise a non-function member.
763                             # Look for a normal decl - "type name[,name...]"
767                                 for name in r.group(2).split(','):
768                                     name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name)
771                                         newmember += f"{r.group(1)} {name}; "
773                                         newmember += f"{r.group(1)} {s_id}.{name}; "
782             # End of the tuple loop - search again and see if there are outer members
816                     level -= 1
827         Store an entry for a ``struct`` or ``union``
840         if self.entry.identifier != declaration_name:
841             self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
864                                 purpose=self.entry.declaration_purpose)
878         # Parse out the name and members of the enum.  Typedef form first.
901         if self.entry.identifier != declaration_name:
902             if self.entry.identifier == "":
904                               f"{proto}: wrong kernel-doc identifier on prototype")
907                               f"expecting prototype for enum {self.entry.identifier}. "
914         # Parse out the name of each enum member, and verify that we
924             self.entry.parameterlist.append(arg)
925             if arg not in self.entry.parameterdescs:
926                 self.entry.parameterdescs[arg] = self.undescribed
933         for k in self.entry.parameterdescs:
940                                 purpose=self.entry.declaration_purpose)
981         # Variable name is at the end of the declaration
1008                                 purpose=self.entry.declaration_purpose)
1015         if self.entry.decl_type == "enum":
1017         elif self.entry.decl_type == "typedef":
1019         elif self.entry.decl_type in ["union", "struct"]:
1021         elif self.entry.decl_type == "var":
1025             self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
1045             # is the space after the name of the symbol being defined.
1063         # 2. Function name
1073         # - parport_register_device (function pointer parameters)
1074         # - atomic_set (macro)
1075         # - pci_match_device, __copy_to_user (long return type)
1077         name = r'\w+'
1082         # lets us easily filter out __acquires() and other post-args stuff.  If
1093                 rf'^()({name})\s*{proto_args}',
1094                 rf'^({type1})\s+({name})\s*{proto_args}',
1095                 rf'^({type2})\s*({name})\s*{proto_args}',
1115         if self.entry.identifier != declaration_name:
1116             self.emit_msg(ln, f"expecting prototype for {self.entry.identifier}(). "
1128                                 purpose=self.entry.declaration_purpose,
1157             if self.entry.identifier != declaration_name:
1159 …f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_…
1168                                     purpose=self.entry.declaration_purpose)
1177             if self.entry.identifier != declaration_name:
1179 …f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_…
1184                                     purpose=self.entry.declaration_purpose)
1217                 symbol = symbol[:-len(suffix)]
1229         # start a new entry
1232         # next line is always the function name
1233         self.state = state.NAME
1237         STATE_NAME: Looking for the "name - description" line
1245                 self.entry.begin_section(ln, "Introduction")
1247                 self.entry.begin_section(ln, doc_block.group(1))
1249             self.entry.identifier = self.entry.section
1255             self.entry.identifier = doc_decl.group(1)
1259                 self.entry.decl_type = doc_begin_data.group(1)
1260                 self.entry.identifier = doc_begin_data.group(2)
1265                 self.entry.identifier = doc_begin_func.group(1)
1266                 self.entry.decl_type = "function"
1272 …his comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/ke…
1276             # OK, set up for a new kerneldoc entry.
1279             self.entry.identifier = self.entry.identifier.strip(" ")
1281             self.entry.begin_section(ln + 1)
1285             # (We should be able to capture this from the previous parsing - someday)
1287             r = KernRe("[-:](.*)")
1289                 self.entry.declaration_purpose = trim_whitespace(r.group(1))
1292                 self.entry.declaration_purpose = ""
1294             if not self.entry.declaration_purpose and self.config.wshort_desc:
1298             if not self.entry.identifier and self.entry.decl_type != "enum":
1300                               f"wrong kernel-doc identifier on line:\n{line}")
1305                               f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
1320             # Pick out the name of our new section, tweaking it if need be.
1341             self.entry.begin_section(ln, newsection)
1342             self.entry.leading_space = None
1344             self.entry.add_text(newcontents.lstrip())
1356             r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/')
1360             self.entry.prototype = ""
1361             self.entry.new_start_line = ln + 1
1390                 self.entry.declaration_purpose = \
1391                     trim_whitespace(self.entry.declaration_purpose + ' ' + cont)
1406             self.entry.begin_section(ln, dump = True)
1425             if self.entry.leading_space is None:
1428                     self.entry.leading_space = len(r.group(1))
1430                     self.entry.leading_space = 0
1436             for i in range(0, self.entry.leading_space):
1438                     self.entry.leading_space = i
1443             self.entry.add_text(cont[self.entry.leading_space:])
1457             self.entry.add_text(cont)
1466             self.entry.begin_section(ln, doc_inline_sect.group(1))
1467             self.entry.add_text(doc_inline_sect.group(2).lstrip())
1473             self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
1490             self.entry.add_text(doc_content.group(1))
1507         # Replace SYSCALL_DEFINE with correct return type & function name
1516         # Now delete all of the odd-numbered commas in the proto
1540         # Match tracepoint name based on different patterns
1565             self.entry.identifier = f"trace_{self.entry.identifier}"
1572         # strip C99-style comments to end of line
1578             self.entry.prototype = line
1582                 self.entry.prototype += r.group(1) + " "
1588             self.entry.prototype = KernRe(r'/\*.*\*/').sub('', self.entry.prototype).strip()
1590             # Handle self.entry.prototypes for function pointers like:
1596             self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
1600             if 'SYSCALL_DEFINE' in self.entry.prototype:
1601                 self.entry.prototype = self.syscall_munge(ln,
1602                                                           self.entry.prototype)
1605                 if r.search(self.entry.prototype):
1606                     self.entry.prototype = self.tracepoint_munge(ln,
1607                                                                  self.entry.prototype)
1611             self.dump_function(ln, self.entry.prototype, source)
1619         # Strip C99-style comments and surrounding whitespace
1634                 self.entry.prototype += chunk
1640                     self.entry.brcount += 1
1642                     self.entry.brcount -= 1
1643                 elif chunk == ';' and self.entry.brcount <= 0:
1644                     self.dump_declaration(ln, self.entry.prototype, source)
1651         self.entry.prototype += ' '
1657             self.entry.begin_section(ln, doc_inline_oneline.group(1))
1658             self.entry.add_text(doc_inline_oneline.group(2))
1664         elif self.entry.decl_type == 'function':
1675             self.output_declaration("doc", self.entry.identifier,
1680             self.entry.add_text(doc_content.group(1))
1704         state.NAME:			process_name,
1721         Besides parsing kernel-doc tags, it also parses export symbols.
1752                                           ln, state.name[self.state],
1763                     # it was read twice. Here, we use the already-existing