Lines Matching +full:entry +full:- +full:name
2 # SPDX-License-Identifier: GPL-2.0
22 # Regular expressions used to parse kernel-doc markups at KernelDoc class.
42 # @{section-name}:
55 attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)",
61 type_param = KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
70 NAME = 1 # looking for function name variable in state
71 BODY_MAYBE = 2 # body - or maybe more description
78 name = [ variable in state
80 "NAME",
91 INLINE_NAME = 1 # looking for member name (@foo:)
94 INLINE_ERROR = 4 # error - Comment without header was found.
96 # proper kernel-doc and ignore the rest.
140 # TODO: rename to emit_message after removal of kernel-doc.pl
159 name = self.section
162 if type_param.match(name):
163 name = type_param.group(1)
165 self.parameterdescs[name] = contents
166 self.parameterdesc_start_lines[name] = self.new_start_line
168 self.sectcheck += name + " "
171 elif name == "@...":
172 name = "..."
173 self.parameterdescs[name] = contents
174 self.sectcheck += name + " "
175 self.parameterdesc_start_lines[name] = self.new_start_line
179 if name in self.sections and self.sections[name] != "":
180 # Only warn on user-specified duplicate section names
181 if name != SECTION_DEFAULT:
183 f"duplicate section name '{name}'\n")
184 self.sections[name] += contents
186 self.sections[name] = contents
187 self.sectionlist.append(name)
188 self.section_start_lines[name] = self.new_start_line
191 # self.config.log.debug("Section: %s : %s", name, pformat(vars(self)))
210 undescribed = "-- undescribed --"
222 # Store entry currently being processed
223 self.entry = None
233 if self.entry:
234 self.entry.emit_msg(log_msg, warning)
247 if self.entry:
248 self.entry.dump_section(start_new)
250 # TODO: rename it to store_declaration after removal of kernel-doc.pl
251 def output_declaration(self, dtype, name, **args): argument
253 Stores the entry into an entry array.
258 # The implementation here is different than the original kernel-doc:
263 # For now, we're keeping the same name of the function just to make
266 args["declaration_start_line"] = self.entry.declaration_start_line
268 args["warnings"] = self.entry.warnings
283 self.entries.append((name, args))
285 self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
289 Ancillary routine to create a new entry. It initializes all
293 self.entry = KernelEntry(self.config, ln)
302 Store parameters and their descriptions at self.entry.
305 if self.entry.anon_struct_union and dtype == "" and param == "}":
308 self.entry.anon_struct_union = False
316 param = param[:-3]
321 if param not in self.entry.parameterdescs or \
322 not self.entry.parameterdescs[param]:
324 self.entry.parameterdescs[param] = "variable arguments"
328 self.entry.parameterdescs[param] = "no arguments"
334 self.entry.parameterdescs[param] = "anonymous\n"
335 self.entry.anon_struct_union = True
346 if param not in self.entry.parameterdescs and not param.startswith("#"):
347 self.entry.parameterdescs[param] = self.undescribed
366 self.entry.parameterlist.append(param)
368 self.entry.parametertypes[param] = org_arg
378 self.entry.struct_actual += actual + " "
383 Creates a list of parameters, storing them at self.entry.
412 # Pointer-to-function
429 # Array-of-pointers
485 if dtype != "": # Skip unnamed bit-fields
547 if not self.entry.sections.get("Return", None):
553 Store an entry for an struct or union
591 if self.entry.identifier != declaration_name:
593 …f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {decl…
616 # __struct_group(TAG, NAME, ATTRS, MEMBERS...)
617 # which has variants like: struct_group(NAME, MEMBERS...)
635 # - a recursive pattern: (?1)
636 # - an atomic grouping: (?>...)
663 …*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'unsigned long \1[1 << ((\2) - 1)]'),
687 # Keeps the original declaration as-is
692 # This loop was simpler at the original kernel-doc perl version, as
732 # Pointer-to-function
734 name = r.group(2)
737 if not name:
742 newmember += f"{dtype}{name}{extra}; "
744 newmember += f"{dtype}{s_id}.{name}{extra}; "
766 for name in names.split(','):
767 name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name).strip()
769 if not name:
774 newmember += f"{dtype} {name}; "
776 newmember += f"{dtype} {s_id}.{name}; "
786 self.entry.sectcheck, self.entry.struct_actual)
812 level -= 1
824 parameterlist=self.entry.parameterlist,
825 parameterdescs=self.entry.parameterdescs,
826 parametertypes=self.entry.parametertypes,
827 parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
828 sectionlist=self.entry.sectionlist,
829 sections=self.entry.sections,
830 section_start_lines=self.entry.section_start_lines,
831 purpose=self.entry.declaration_purpose)
865 if self.entry.identifier != declaration_name:
866 if self.entry.identifier == "":
868 f"{proto}: wrong kernel-doc identifier on prototype")
871 …f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} …
885 self.entry.parameterlist.append(arg)
886 if arg not in self.entry.parameterdescs:
887 self.entry.parameterdescs[arg] = self.undescribed
892 for k in self.entry.parameterdescs:
899 parameterlist=self.entry.parameterlist,
900 parameterdescs=self.entry.parameterdescs,
901 parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
902 sectionlist=self.entry.sectionlist,
903 sections=self.entry.sections,
904 section_start_lines=self.entry.section_start_lines,
905 purpose=self.entry.declaration_purpose)
912 if self.entry.decl_type == "enum":
916 if self.entry.decl_type == "typedef":
920 if self.entry.decl_type in ["union", "struct"]:
924 self.output_declaration(self.entry.decl_type, prototype,
925 entry=self.entry)
967 # [\w\s]+ # attribute name
991 # 2. Function name
1001 # - parport_register_device (function pointer parameters)
1002 # - atomic_set (macro)
1003 # - pci_match_device, __copy_to_user (long return type)
1005 name = r'[a-zA-Z0-9_~:]+'
1010 # Besides compiling, Perl qr{[\w\s]+} works as a non-capturing group.
1019 r = KernRe(r'^()(' + name + r')\s+')
1030 rf'^()({name})\s*{prototype_end}',
1031 rf'^({type1})\s+({name})\s*{prototype_end}',
1032 rf'^({type2})\s*({name})\s*{prototype_end}',
1054 if self.entry.identifier != declaration_name:
1056 …f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instea…
1059 prms = " ".join(self.entry.parameterlist)
1061 self.entry.sectcheck, prms)
1070 parameterlist=self.entry.parameterlist,
1071 parameterdescs=self.entry.parameterdescs,
1072 parametertypes=self.entry.parametertypes,
1073 parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1074 sectionlist=self.entry.sectionlist,
1075 sections=self.entry.sections,
1076 section_start_lines=self.entry.section_start_lines,
1077 purpose=self.entry.declaration_purpose,
1084 parameterlist=self.entry.parameterlist,
1085 parameterdescs=self.entry.parameterdescs,
1086 parametertypes=self.entry.parametertypes,
1087 parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1088 sectionlist=self.entry.sectionlist,
1089 sections=self.entry.sections,
1090 section_start_lines=self.entry.section_start_lines,
1091 purpose=self.entry.declaration_purpose,
1118 if self.entry.identifier != declaration_name:
1120 …f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_…
1130 parameterlist=self.entry.parameterlist,
1131 parameterdescs=self.entry.parameterdescs,
1132 parametertypes=self.entry.parametertypes,
1133 parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1134 sectionlist=self.entry.sectionlist,
1135 sections=self.entry.sections,
1136 section_start_lines=self.entry.section_start_lines,
1137 purpose=self.entry.declaration_purpose)
1150 if self.entry.identifier != declaration_name:
1152 …f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_…
1157 sectionlist=self.entry.sectionlist,
1158 sections=self.entry.sections,
1159 section_start_lines=self.entry.section_start_lines,
1160 purpose=self.entry.declaration_purpose)
1194 # start a new entry
1196 self.entry.in_doc_sect = False
1198 # next line is always the function name
1199 self.state = state.NAME
1203 STATE_NAME: Looking for the "name - description" line
1207 self.entry.new_start_line = ln
1210 self.entry.section = self.section_intro
1212 self.entry.section = doc_block.group(1)
1214 self.entry.identifier = self.entry.section
1219 self.entry.identifier = doc_decl.group(1)
1220 self.entry.is_kernel_comment = False
1223 fn_type = r"(?:\w+\s*\*\s*)?" # type (for non-functions)
1225 decl_end = r"(?:[-:].*)" # end of the name part
1227 # test for pointer declaration type, foo * bar() - desc
1230 self.entry.identifier = r.group(1)
1235 self.entry.decl_type = r.group(1)
1236 self.entry.identifier = r.group(2)
1237 self.entry.is_kernel_comment = True
1239 # Look for foo() or static void foo() - description;
1243 r2 = KernRe(fr"^{decl_start}{fn_type}(\w+[^-:]*){parenthesis}\s*{decl_end}$")
1247 self.entry.identifier = r.group(1)
1248 self.entry.decl_type = "function"
1251 self.entry.identifier = r.sub("", self.entry.identifier)
1252 self.entry.is_kernel_comment = True
1255 self.entry.identifier = self.entry.identifier.strip(" ")
1260 self.entry.section = SECTION_DEFAULT
1261 self.entry.new_start_line = ln + 1
1263 r = KernRe("[-:](.*)")
1266 self.entry.descr = r.group(1).strip(" ")
1269 self.entry.descr = r.sub(" ", self.entry.descr)
1270 self.entry.declaration_purpose = self.entry.descr
1273 self.entry.declaration_purpose = ""
1275 if not self.entry.is_kernel_comment:
1277 …"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/ker…
1280 if not self.entry.declaration_purpose and self.config.wshort_desc:
1284 if not self.entry.identifier and self.entry.decl_type != "enum":
1286 f"wrong kernel-doc identifier on line:\n{line}")
1291 f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
1308 self.entry.section = SECTION_DEFAULT
1309 self.entry.new_start_line = ln
1310 self.entry.contents = ""
1313 self.entry.in_doc_sect = True
1324 # Perl kernel-doc has a check here for contents before sections.
1333 if self.entry.contents.strip("\n"):
1336 self.entry.new_start_line = ln
1337 self.entry.section = newsection
1338 self.entry.leading_space = None
1340 self.entry.contents = newcontents.lstrip()
1341 if self.entry.contents:
1342 self.entry.contents += "\n"
1351 r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/')
1355 self.entry.prototype = ""
1356 self.entry.new_start_line = ln + 1
1365 if self.entry.section == self.section_context:
1368 self.entry.new_start_line = ln
1371 if self.entry.section != SECTION_DEFAULT:
1376 self.entry.contents += "\n"
1381 self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip()
1382 self.entry.declaration_purpose += " " + cont
1385 self.entry.declaration_purpose = r.sub(' ',
1386 self.entry.declaration_purpose)
1389 if self.entry.section.startswith('@') or \
1390 self.entry.section == self.section_context:
1391 if self.entry.leading_space is None:
1394 self.entry.leading_space = len(r.group(1))
1396 self.entry.leading_space = 0
1398 # Double-check if leading space are realy spaces
1400 for i in range(0, self.entry.leading_space):
1409 if self.entry.leading_space != pos:
1410 self.entry.leading_space = pos
1412 self.entry.contents += cont + "\n"
1423 self.entry.section = doc_inline_sect.group(1)
1424 self.entry.new_start_line = ln
1426 self.entry.contents = doc_inline_sect.group(2).lstrip()
1427 if self.entry.contents != "":
1428 self.entry.contents += "\n"
1435 if self.entry.contents not in ["", "\n"]:
1444 self.entry.contents += doc_content.group(1) + "\n"
1445 if not self.entry.contents.strip(" ").rstrip("\n"):
1446 self.entry.contents = ""
1450 f"Incorrect use of kernel-doc format: {line}")
1468 # Replace SYSCALL_DEFINE with correct return type & function name
1477 # Now delete all of the odd-numbered commas in the proto
1501 # Match tracepoint name based on different patterns
1526 self.entry.identifier = f"trace_{self.entry.identifier}"
1533 # strip C99-style comments to end of line
1538 self.entry.prototype = line
1545 self.entry.prototype += r.group(1) + " "
1550 self.entry.prototype = r.sub('', self.entry.prototype)
1554 self.entry.prototype = r.sub(' ', self.entry.prototype)
1558 self.entry.prototype = r.sub('', self.entry.prototype)
1560 # Handle self.entry.prototypes for function pointers like:
1564 self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
1566 if 'SYSCALL_DEFINE' in self.entry.prototype:
1567 self.entry.prototype = self.syscall_munge(ln,
1568 self.entry.prototype)
1571 if r.search(self.entry.prototype):
1572 self.entry.prototype = self.tracepoint_munge(ln,
1573 self.entry.prototype)
1575 self.dump_function(ln, self.entry.prototype)
1590 # Strip C99-style comments to the end of the line
1600 if self.entry.prototype:
1601 self.entry.prototype += " "
1602 self.entry.prototype += r.group(1) + r.group(2)
1604 self.entry.brcount += r.group(2).count('{')
1605 self.entry.brcount -= r.group(2).count('}')
1607 self.entry.brcount = max(self.entry.brcount, 0)
1609 if r.group(2) == ';' and self.entry.brcount == 0:
1610 self.dump_declaration(ln, self.entry.prototype)
1616 self.entry.prototype += line
1623 self.entry.section = doc_inline_oneline.group(1)
1624 self.entry.contents = doc_inline_oneline.group(2)
1626 if self.entry.contents != "":
1627 self.entry.contents += "\n"
1634 elif self.entry.decl_type == 'function':
1645 self.output_declaration("doc", self.entry.identifier,
1646 sectionlist=self.entry.sectionlist,
1647 sections=self.entry.sections,
1648 section_start_lines=self.entry.section_start_lines)
1652 self.entry.contents += doc_content.group(1) + "\n"
1680 Besides parsing kernel-doc tags, it also parses export symbols.
1714 ln, state.name[self.state],
1720 # it was read twice. Here, we use the already-existing
1731 elif self.state == state.NAME: