Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kdoc: Coalesce parameter-list handling
Callers to output_declaration() always pass the parameter information from
self.entry; remove all of the boilerplate arguments and just get at that
information directly. Formalize its placement in the KdocItem class.
It would be nice to get rid of parameterlist as well, but that has the
effect of reordering the output of function parameters and struct fields to
match the order in the kerneldoc comment rather than in the declaration.
One could argue about which is more correct, but the ordering has been left
unchanged for now.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
+43
-67
+11
-1
scripts/lib/kdoc/kdoc_item.py
+11
-1
scripts/lib/kdoc/kdoc_item.py
···
11
11
self.declaration_start_line = start_line
12
12
self.sections = {}
13
13
self.sections_start_lines = {}
14
+
self.parameterlist = []
15
+
self.parameterdesc_start_lines = []
16
+
self.parameterdescs = {}
17
+
self.parametertypes = {}
14
18
#
15
19
# Just save everything else into our own dict so that the output
16
20
# side can grab it directly as before. As we move things into more
···
32
28
return self.get(key)
33
29
34
30
#
35
-
# Tracking of section information.
31
+
# Tracking of section and parameter information.
36
32
#
37
33
def set_sections(self, sections, start_lines):
38
34
self.sections = sections
39
35
self.section_start_lines = start_lines
36
+
37
+
def set_params(self, names, descs, types, starts):
38
+
self.parameterlist = names
39
+
self.parameterdescs = descs
40
+
self.parametertypes = types
41
+
self.parameterdesc_start_lines = starts
+29
-46
scripts/lib/kdoc/kdoc_output.py
+29
-46
scripts/lib/kdoc/kdoc_output.py
···
373
373
signature = args['functiontype'] + " "
374
374
signature += args['function'] + " ("
375
375
376
-
parameterlist = args.get('parameterlist', [])
377
-
parameterdescs = args.get('parameterdescs', {})
378
-
parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
379
-
380
376
ln = args.get('declaration_start_line', 0)
381
-
382
377
count = 0
383
-
for parameter in parameterlist:
378
+
for parameter in args.parameterlist:
384
379
if count != 0:
385
380
signature += ", "
386
381
count += 1
387
-
dtype = args['parametertypes'].get(parameter, "")
382
+
dtype = args.parametertypes.get(parameter, "")
388
383
389
384
if function_pointer.search(dtype):
390
385
signature += function_pointer.group(1) + parameter + function_pointer.group(3)
···
414
419
# function prototypes apart
415
420
self.lineprefix = " "
416
421
417
-
if parameterlist:
422
+
if args.parameterlist:
418
423
self.data += ".. container:: kernelindent\n\n"
419
424
self.data += f"{self.lineprefix}**Parameters**\n\n"
420
425
421
-
for parameter in parameterlist:
426
+
for parameter in args.parameterlist:
422
427
parameter_name = KernRe(r'\[.*').sub('', parameter)
423
-
dtype = args['parametertypes'].get(parameter, "")
428
+
dtype = args.parametertypes.get(parameter, "")
424
429
425
430
if dtype:
426
431
self.data += f"{self.lineprefix}``{dtype}``\n"
427
432
else:
428
433
self.data += f"{self.lineprefix}``{parameter}``\n"
429
434
430
-
self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
435
+
self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
431
436
432
437
self.lineprefix = " "
433
-
if parameter_name in parameterdescs and \
434
-
parameterdescs[parameter_name] != KernelDoc.undescribed:
438
+
if parameter_name in args.parameterdescs and \
439
+
args.parameterdescs[parameter_name] != KernelDoc.undescribed:
435
440
436
-
self.output_highlight(parameterdescs[parameter_name])
441
+
self.output_highlight(args.parameterdescs[parameter_name])
437
442
self.data += "\n"
438
443
else:
439
444
self.data += f"{self.lineprefix}*undescribed*\n\n"
···
446
451
447
452
oldprefix = self.lineprefix
448
453
name = args.get('enum', '')
449
-
parameterlist = args.get('parameterlist', [])
450
-
parameterdescs = args.get('parameterdescs', {})
451
454
ln = args.get('declaration_start_line', 0)
452
455
453
456
self.data += f"\n\n.. c:enum:: {name}\n\n"
···
460
467
self.lineprefix = outer + " "
461
468
self.data += f"{outer}**Constants**\n\n"
462
469
463
-
for parameter in parameterlist:
470
+
for parameter in args.parameterlist:
464
471
self.data += f"{outer}``{parameter}``\n"
465
472
466
-
if parameterdescs.get(parameter, '') != KernelDoc.undescribed:
467
-
self.output_highlight(parameterdescs[parameter])
473
+
if args.parameterdescs.get(parameter, '') != KernelDoc.undescribed:
474
+
self.output_highlight(args.parameterdescs[parameter])
468
475
else:
469
476
self.data += f"{self.lineprefix}*undescribed*\n\n"
470
477
self.data += "\n"
···
498
505
dtype = args.get('type', "struct")
499
506
ln = args.get('declaration_start_line', 0)
500
507
501
-
parameterlist = args.get('parameterlist', [])
502
-
parameterdescs = args.get('parameterdescs', {})
503
-
parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
504
-
505
508
self.data += f"\n\n.. c:{dtype}:: {name}\n\n"
506
509
507
510
self.print_lineno(ln)
···
520
531
521
532
self.lineprefix = " "
522
533
self.data += f"{self.lineprefix}**Members**\n\n"
523
-
for parameter in parameterlist:
534
+
for parameter in args.parameterlist:
524
535
if not parameter or parameter.startswith("#"):
525
536
continue
526
537
527
538
parameter_name = parameter.split("[", maxsplit=1)[0]
528
539
529
-
if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
540
+
if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
530
541
continue
531
542
532
-
self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
543
+
self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
533
544
534
545
self.data += f"{self.lineprefix}``{parameter}``\n"
535
546
536
547
self.lineprefix = " "
537
-
self.output_highlight(parameterdescs[parameter_name])
548
+
self.output_highlight(args.parameterdescs[parameter_name])
538
549
self.lineprefix = " "
539
550
540
551
self.data += "\n"
···
632
643
def out_function(self, fname, name, args):
633
644
"""output function in man"""
634
645
635
-
parameterlist = args.get('parameterlist', [])
636
-
parameterdescs = args.get('parameterdescs', {})
637
-
638
646
self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
639
647
640
648
self.data += ".SH NAME\n"
···
647
661
parenth = "("
648
662
post = ","
649
663
650
-
for parameter in parameterlist:
651
-
if count == len(parameterlist) - 1:
664
+
for parameter in args.parameterlist:
665
+
if count == len(args.parameterlist) - 1:
652
666
post = ");"
653
667
654
-
dtype = args['parametertypes'].get(parameter, "")
668
+
dtype = args.parametertypes.get(parameter, "")
655
669
if function_pointer.match(dtype):
656
670
# Pointer-to-function
657
671
self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n"
···
662
676
count += 1
663
677
parenth = ""
664
678
665
-
if parameterlist:
679
+
if args.parameterlist:
666
680
self.data += ".SH ARGUMENTS\n"
667
681
668
-
for parameter in parameterlist:
682
+
for parameter in args.parameterlist:
669
683
parameter_name = re.sub(r'\[.*', '', parameter)
670
684
671
685
self.data += f'.IP "{parameter}" 12' + "\n"
672
-
self.output_highlight(parameterdescs.get(parameter_name, ""))
686
+
self.output_highlight(args.parameterdescs.get(parameter_name, ""))
673
687
674
688
for section, text in args.sections.items():
675
689
self.data += f'.SH "{section.upper()}"' + "\n"
···
678
692
def out_enum(self, fname, name, args):
679
693
680
694
name = args.get('enum', '')
681
-
parameterlist = args.get('parameterlist', [])
682
695
683
696
self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
684
697
···
688
703
self.data += f"enum {args['enum']}" + " {\n"
689
704
690
705
count = 0
691
-
for parameter in parameterlist:
706
+
for parameter in args.parameterlist:
692
707
self.data += f'.br\n.BI " {parameter}"' + "\n"
693
-
if count == len(parameterlist) - 1:
708
+
if count == len(args.parameterlist) - 1:
694
709
self.data += "\n};\n"
695
710
else:
696
711
self.data += ", \n.br\n"
···
699
714
700
715
self.data += ".SH Constants\n"
701
716
702
-
for parameter in parameterlist:
717
+
for parameter in args.parameterlist:
703
718
parameter_name = KernRe(r'\[.*').sub('', parameter)
704
719
self.data += f'.IP "{parameter}" 12' + "\n"
705
-
self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
720
+
self.output_highlight(args.parameterdescs.get(parameter_name, ""))
706
721
707
722
for section, text in args.sections.items():
708
723
self.data += f'.SH "{section}"' + "\n"
···
728
743
struct_name = args.get('struct')
729
744
purpose = args.get('purpose')
730
745
definition = args.get('definition')
731
-
parameterlist = args.get('parameterlist', [])
732
-
parameterdescs = args.get('parameterdescs', {})
733
746
734
747
self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
735
748
···
743
760
self.data += f'.BI "{declaration}\n' + "};\n.br\n\n"
744
761
745
762
self.data += ".SH Members\n"
746
-
for parameter in parameterlist:
763
+
for parameter in args.parameterlist:
747
764
if parameter.startswith("#"):
748
765
continue
749
766
750
767
parameter_name = re.sub(r"\[.*", "", parameter)
751
768
752
-
if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
769
+
if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
753
770
continue
754
771
755
772
self.data += f'.IP "{parameter}" 12' + "\n"
756
-
self.output_highlight(parameterdescs.get(parameter_name))
773
+
self.output_highlight(args.parameterdescs.get(parameter_name))
757
774
758
775
for section, text in args.sections.items():
759
776
self.data += f'.SH "{section}"' + "\n"
+3
-20
scripts/lib/kdoc/kdoc_parser.py
+3
-20
scripts/lib/kdoc/kdoc_parser.py
···
278
278
if section in sections and not sections[section].rstrip():
279
279
del sections[section]
280
280
item.set_sections(sections, self.entry.section_start_lines)
281
-
281
+
item.set_params(self.entry.parameterlist, self.entry.parameterdescs,
282
+
self.entry.parametertypes,
283
+
self.entry.parameterdesc_start_lines)
282
284
self.entries.append(item)
283
285
284
286
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
···
792
790
self.output_declaration(decl_type, declaration_name,
793
791
struct=declaration_name,
794
792
definition=declaration,
795
-
parameterlist=self.entry.parameterlist,
796
-
parameterdescs=self.entry.parameterdescs,
797
-
parametertypes=self.entry.parametertypes,
798
-
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
799
793
purpose=self.entry.declaration_purpose)
800
794
801
795
def dump_enum(self, ln, proto):
···
871
873
872
874
self.output_declaration('enum', declaration_name,
873
875
enum=declaration_name,
874
-
parameterlist=self.entry.parameterlist,
875
-
parameterdescs=self.entry.parameterdescs,
876
-
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
877
876
purpose=self.entry.declaration_purpose)
878
877
879
878
def dump_declaration(self, ln, prototype):
···
1034
1039
function=declaration_name,
1035
1040
typedef=True,
1036
1041
functiontype=return_type,
1037
-
parameterlist=self.entry.parameterlist,
1038
-
parameterdescs=self.entry.parameterdescs,
1039
-
parametertypes=self.entry.parametertypes,
1040
-
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1041
1042
purpose=self.entry.declaration_purpose,
1042
1043
func_macro=func_macro)
1043
1044
else:
···
1041
1050
function=declaration_name,
1042
1051
typedef=False,
1043
1052
functiontype=return_type,
1044
-
parameterlist=self.entry.parameterlist,
1045
-
parameterdescs=self.entry.parameterdescs,
1046
-
parametertypes=self.entry.parametertypes,
1047
-
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1048
1053
purpose=self.entry.declaration_purpose,
1049
1054
func_macro=func_macro)
1050
1055
···
1080
1093
function=declaration_name,
1081
1094
typedef=True,
1082
1095
functiontype=return_type,
1083
-
parameterlist=self.entry.parameterlist,
1084
-
parameterdescs=self.entry.parameterdescs,
1085
-
parametertypes=self.entry.parametertypes,
1086
-
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
1087
1096
purpose=self.entry.declaration_purpose)
1088
1097
return
1089
1098