History

Merge tag 'docs/v5.10-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull documentation updates from Mauro Carvalho Chehab: "A series of patches addressing warnings produced by make htmldocs. This includes: - kernel-doc markup fixes - ReST fixes - Updates at the build system in order to support newer versions of the docs build toolchain (Sphinx) After this series, the number of html build warnings should reduce significantly, and building with Sphinx 3.1 or later should now be supported (although it is still recommended to use Sphinx 2.4.4). As agreed with Jon, I should be sending you a late pull request by the end of the merge window addressing remaining issues with docs build, as there are a number of warning fixes that depends on pull requests that should be happening along the merge window. The end goal is to have a clean htmldocs build on Kernel 5.10. PS. It should be noticed that Sphinx 3.0 is not currently supported, as it lacks support for C domain namespaces. Such feature, needed in order to document uAPI system calls with Sphinx 3.x, was added only on Sphinx 3.1" * tag 'docs/v5.10-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (75 commits) PM / devfreq: remove a duplicated kernel-doc markup mm/doc: fix a literal block markup workqueue: fix a kernel-doc warning docs: virt: user_mode_linux_howto_v2.rst: fix a literal block markup Input: sparse-keymap: add a description for @sw rcu/tree: docs: document bkvcache new members at struct kfree_rcu_cpu nl80211: docs: add a description for s1g_cap parameter usb: docs: document altmode register/unregister functions kunit: test.h: fix a bad kernel-doc markup drivers: core: fix kernel-doc markup for dev_err_probe() docs: bio: fix a kerneldoc markup kunit: test.h: solve kernel-doc warnings block: bio: fix a warning at the kernel-doc markups docs: powerpc: syscall64-abi.rst: fix a malformed table drivers: net: hamradio: fix document location net: appletalk: Kconfig: Fix docs location dt-bindings: fix references to files converted to yaml memblock: get rid of a :c:type leftover math64.h: kernel-docs: Convert some markups into normal comments media: uAPI: buffer.rst: remove a left-over documentation ...

Linus Torvalds committed 6 years ago

Commit 54a4c782 parents 93f3d8f 3e2ac97309 files · +1952 −2275Browse files

Showing the changes to scripts (1 of 309 files). Show all

Unified · Split

scripts/kernel-doc+223−82
@@ -56,6 +56,13 @@ Output format selection (mutually exclusive): · 55 unmodified lines
56 -rst Output reStructuredText format.56 -rst Output reStructuredText format.
57 -none Do not output documentation, only warnings.57 -none Do not output documentation, only warnings.
58 58
59Output format selection modifier (affects only ReST output):
60
61 -sphinx-version Use the ReST C domain dialect compatible with an
62 specific Sphinx Version.
63 If not specified, kernel-doc will auto-detect using
64 the sphinx-build version found on PATH.
65
59Output selection (mutually exclusive):66Output selection (mutually exclusive):
60 -export Only output documentation for symbols that have been67 -export Only output documentation for symbols that have been
61 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()68 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -66,9 +73,8 @@ Output selection (mutually exclusive): · 4 unmodified lines
66 -function NAME Only output documentation for the given function(s)73 -function NAME Only output documentation for the given function(s)
67 or DOC: section title(s). All other functions and DOC:74 or DOC: section title(s). All other functions and DOC:
68 sections are ignored. May be specified multiple times.75 sections are ignored. May be specified multiple times.
69 -nofunction NAME Do NOT output documentation for the given function(s);76 -nosymbol NAME Exclude the specified symbols from the output
70 only output documentation for the other functions and77 documentation. May be specified multiple times.
71 DOC: sections. May be specified multiple times.
72 78
73Output selection modifiers:79Output selection modifiers:
74 -no-doc-sections Do not output DOC: sections.80 -no-doc-sections Do not output DOC: sections.
@@ -271,6 +277,8 @@ if ($#ARGV == -1) { · 196 unmodified lines
271}277}
272 278
273my $kernelversion;279my $kernelversion;
280my ($sphinx_major, $sphinx_minor, $sphinx_patch);
281
274my $dohighlight = "";282my $dohighlight = "";
275 283
276my $verbose = 0;284my $verbose = 0;
@@ -286,9 +294,8 @@ my $modulename = "Kernel API"; · 9 unmodified lines
286use constant {294use constant {
287 OUTPUT_ALL => 0, # output all symbols and doc sections295 OUTPUT_ALL => 0, # output all symbols and doc sections
288 OUTPUT_INCLUDE => 1, # output only specified symbols296 OUTPUT_INCLUDE => 1, # output only specified symbols
289 OUTPUT_EXCLUDE => 2, # output everything except specified symbols297 OUTPUT_EXPORTED => 2, # output exported symbols
290 OUTPUT_EXPORTED => 3, # output exported symbols298 OUTPUT_INTERNAL => 3, # output non-exported symbols
291 OUTPUT_INTERNAL => 4, # output non-exported symbols
292};299};
293my $output_selection = OUTPUT_ALL;300my $output_selection = OUTPUT_ALL;
294my $show_not_found = 0; # No longer used301my $show_not_found = 0; # No longer used
@@ -313,6 +320,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', · 18 unmodified lines
313# CAVEAT EMPTOR! Some of the others I localised may not want to be, which320# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
314# could cause "use of undefined value" or other bugs.321# could cause "use of undefined value" or other bugs.
315my ($function, %function_table, %parametertypes, $declaration_purpose);322my ($function, %function_table, %parametertypes, $declaration_purpose);
323my %nosymbol_table = ();
316my $declaration_start_line;324my $declaration_start_line;
317my ($type, $declaration_name, $return_type);325my ($type, $declaration_name, $return_type);
318my ($newsection, $newcontents, $prototype, $brcount, %source_map);326my ($newsection, $newcontents, $prototype, $brcount, %source_map);
@@ -432,10 +440,9 @@ while ($ARGV[0] =~ m/^--?(.*)/) { · 113 unmodified lines
432 $output_selection = OUTPUT_INCLUDE;440 $output_selection = OUTPUT_INCLUDE;
433 $function = shift @ARGV;441 $function = shift @ARGV;
434 $function_table{$function} = 1;442 $function_table{$function} = 1;
435 } elsif ($cmd eq "nofunction") { # output all except specific functions443 } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
436 $output_selection = OUTPUT_EXCLUDE;444 my $symbol = shift @ARGV;
437 $function = shift @ARGV;445 $nosymbol_table{$symbol} = 1;
438 $function_table{$function} = 1;
439 } elsif ($cmd eq "export") { # only exported symbols446 } elsif ($cmd eq "export") { # only exported symbols
440 $output_selection = OUTPUT_EXPORTED;447 $output_selection = OUTPUT_EXPORTED;
441 %function_table = ();448 %function_table = ();
@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) { · 15 unmodified lines
457 $enable_lineno = 1;464 $enable_lineno = 1;
458 } elsif ($cmd eq 'show-not-found') {465 } elsif ($cmd eq 'show-not-found') {
459 $show_not_found = 1; # A no-op but don't fail466 $show_not_found = 1; # A no-op but don't fail
467 } elsif ($cmd eq "sphinx-version") {
468 my $ver_string = shift @ARGV;
469 if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
470 $sphinx_major = $1;
471 if (defined($2)) {
472 $sphinx_minor = substr($2,1);
473 } else {
474 $sphinx_minor = 0;
475 }
476 if (defined($3)) {
477 $sphinx_patch = substr($3,1)
478 } else {
479 $sphinx_patch = 0;
480 }
481 } else {
482 die "Sphinx version should either major.minor or major.minor.patch format\n";
483 }
460 } else {484 } else {
461 # Unknown argument485 # Unknown argument
462 usage();486 usage();
@@ -465,6 +489,51 @@ while ($ARGV[0] =~ m/^--?(.*)/) { · 2 unmodified lines
465 489
466# continue execution near EOF;490# continue execution near EOF;
467 491
492# The C domain dialect changed on Sphinx 3. So, we need to check the
493# version in order to produce the right tags.
494sub findprog($)
495{
496 foreach(split(/:/, $ENV{PATH})) {
497 return "$_/$_[0]" if(-x "$_/$_[0]");
498 }
499}
500
501sub get_sphinx_version()
502{
503 my $ver;
504
505 my $cmd = "sphinx-build";
506 if (!findprog($cmd)) {
507 my $cmd = "sphinx-build3";
508 if (!findprog($cmd)) {
509 $sphinx_major = 1;
510 $sphinx_minor = 2;
511 $sphinx_patch = 0;
512 printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
513 $sphinx_major, $sphinx_minor, $sphinx_patch;
514 return;
515 }
516 }
517
518 open IN, "$cmd --version 2>&1 |";
519 while (<IN>) {
520 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
521 $sphinx_major = $1;
522 $sphinx_minor = $2;
523 $sphinx_patch = $3;
524 last;
525 }
526 # Sphinx 1.2.x uses a different format
527 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
528 $sphinx_major = $1;
529 $sphinx_minor = $2;
530 $sphinx_patch = $3;
531 last;
532 }
533 }
534 close IN;
535}
536
468# get kernel version from env537# get kernel version from env
469sub get_kernel_version() {538sub get_kernel_version() {
470 my $version = 'unknown kernel version';539 my $version = 'unknown kernel version';
@@ -531,11 +600,11 @@ sub dump_doc_section { · 60 unmodified lines
531 return;600 return;
532 }601 }
533 602
603 return if (defined($nosymbol_table{$name}));
604
534 if (($output_selection == OUTPUT_ALL) ||605 if (($output_selection == OUTPUT_ALL) ||
535 ($output_selection == OUTPUT_INCLUDE &&606 (($output_selection == OUTPUT_INCLUDE) &&
536 defined($function_table{$name})) ||607 defined($function_table{$name})))
537 ($output_selection == OUTPUT_EXCLUDE &&
538 !defined($function_table{$name})))
539 {608 {
540 dump_section($file, $name, $contents);609 dump_section($file, $name, $contents);
541 output_blockhead({'sectionlist' => \@sectionlist,610 output_blockhead({'sectionlist' => \@sectionlist,
@@ -618,10 +687,10 @@ sub output_function_man(%) { · 76 unmodified lines
618 $type = $args{'parametertypes'}{$parameter};687 $type = $args{'parametertypes'}{$parameter};
619 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {688 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
620 # pointer-to-function689 # pointer-to-function
621 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";690 print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
622 } else {691 } else {
623 $type =~ s/([^\*])$/$1 /;692 $type =~ s/([^\*])$/$1 /;
624 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";693 print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
625 }694 }
626 $count++;695 $count++;
627 $parenth = "";696 $parenth = "";
@@ -761,6 +830,8 @@ sub output_blockhead_rst(%) { · 133 unmodified lines
761 my ($parameter, $section);830 my ($parameter, $section);
762 831
763 foreach $section (@{$args{'sectionlist'}}) {832 foreach $section (@{$args{'sectionlist'}}) {
833 next if (defined($nosymbol_table{$section}));
834
764 if ($output_selection != OUTPUT_INCLUDE) {835 if ($output_selection != OUTPUT_INCLUDE) {
765 print "**$section**\n\n";836 print "**$section**\n\n";
766 }837 }
@@ -846,16 +917,37 @@ sub output_function_rst(%) { · 79 unmodified lines
846 my ($parameter, $section);917 my ($parameter, $section);
847 my $oldprefix = $lineprefix;918 my $oldprefix = $lineprefix;
848 my $start = "";919 my $start = "";
849 920 my $is_macro = 0;
850 if ($args{'typedef'}) {921
851 print ".. c:type:: ". $args{'function'} . "\n\n";922 if ($sphinx_major < 3) {
852 print_lineno($declaration_start_line);923 if ($args{'typedef'}) {
853 print " **Typedef**: ";924 print ".. c:type:: ". $args{'function'} . "\n\n";
854 $lineprefix = "";925 print_lineno($declaration_start_line);
855 output_highlight_rst($args{'purpose'});926 print " **Typedef**: ";
856 $start = "\n\n**Syntax**\n\n ``";927 $lineprefix = "";
928 output_highlight_rst($args{'purpose'});
929 $start = "\n\n**Syntax**\n\n ``";
930 $is_macro = 1;
931 } else {
932 print ".. c:function:: ";
933 }
857 } else {934 } else {
858 print ".. c:function:: ";935 if ($args{'typedef'} || $args{'functiontype'} eq "") {
936 $is_macro = 1;
937 print ".. c:macro:: ". $args{'function'} . "\n\n";
938 } else {
939 print ".. c:function:: ";
940 }
941
942 if ($args{'typedef'}) {
943 print_lineno($declaration_start_line);
944 print " **Typedef**: ";
945 $lineprefix = "";
946 output_highlight_rst($args{'purpose'});
947 $start = "\n\n**Syntax**\n\n ``";
948 } else {
949 print "``" if ($is_macro);
950 }
859 }951 }
860 if ($args{'functiontype'} ne "") {952 if ($args{'functiontype'} ne "") {
861 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";953 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -876,13 +968,15 @@ sub output_function_rst(%) { · 14 unmodified lines
876 # pointer-to-function968 # pointer-to-function
877 print $1 . $parameter . ") (" . $2 . ")";969 print $1 . $parameter . ") (" . $2 . ")";
878 } else {970 } else {
879 print $type . " " . $parameter;971 print $type;
880 }972 }
881 }973 }
882 if ($args{'typedef'}) {974 if ($is_macro) {
883 print ");``\n\n";975 print ")``\n\n";
884 } else {976 } else {
885 print ")\n\n";977 print ")\n\n";
978 }
979 if (!$args{'typedef'}) {
886 print_lineno($declaration_start_line);980 print_lineno($declaration_start_line);
887 $lineprefix = " ";981 $lineprefix = " ";
888 output_highlight_rst($args{'purpose'});982 output_highlight_rst($args{'purpose'});
@@ -897,7 +991,7 @@ sub output_function_rst(%) { · 8 unmodified lines
897 $type = $args{'parametertypes'}{$parameter};991 $type = $args{'parametertypes'}{$parameter};
898 992
899 if ($type ne "") {993 if ($type ne "") {
900 print "``$type $parameter``\n";994 print "``$type``\n";
901 } else {995 } else {
902 print "``$parameter``\n";996 print "``$parameter``\n";
903 }997 }
@@ -938,9 +1032,14 @@ sub output_enum_rst(%) { · 34 unmodified lines
938 my ($parameter);1032 my ($parameter);
939 my $oldprefix = $lineprefix;1033 my $oldprefix = $lineprefix;
940 my $count;1034 my $count;
941 my $name = "enum " . $args{'enum'};
942 1035
943 print "\n\n.. c:type:: " . $name . "\n\n";1036 if ($sphinx_major < 3) {
1037 my $name = "enum " . $args{'enum'};
1038 print "\n\n.. c:type:: " . $name . "\n\n";
1039 } else {
1040 my $name = $args{'enum'};
1041 print "\n\n.. c:enum:: " . $name . "\n\n";
1042 }
944 print_lineno($declaration_start_line);1043 print_lineno($declaration_start_line);
945 $lineprefix = " ";1044 $lineprefix = " ";
946 output_highlight_rst($args{'purpose'});1045 output_highlight_rst($args{'purpose'});
@@ -966,8 +1065,13 @@ sub output_typedef_rst(%) { · 19 unmodified lines
966 my %args = %{$_[0]};1065 my %args = %{$_[0]};
967 my ($parameter);1066 my ($parameter);
968 my $oldprefix = $lineprefix;1067 my $oldprefix = $lineprefix;
969 my $name = "typedef " . $args{'typedef'};1068 my $name;
970 1069
1070 if ($sphinx_major < 3) {
1071 $name = "typedef " . $args{'typedef'};
1072 } else {
1073 $name = $args{'typedef'};
1074 }
971 print "\n\n.. c:type:: " . $name . "\n\n";1075 print "\n\n.. c:type:: " . $name . "\n\n";
972 print_lineno($declaration_start_line);1076 print_lineno($declaration_start_line);
973 $lineprefix = " ";1077 $lineprefix = " ";
@@ -982,9 +1086,14 @@ sub output_struct_rst(%) { · 8 unmodified lines
982 my %args = %{$_[0]};1086 my %args = %{$_[0]};
983 my ($parameter);1087 my ($parameter);
984 my $oldprefix = $lineprefix;1088 my $oldprefix = $lineprefix;
985 my $name = $args{'type'} . " " . $args{'struct'};
986 1089
987 print "\n\n.. c:type:: " . $name . "\n\n";1090 if ($sphinx_major < 3) {
1091 my $name = $args{'type'} . " " . $args{'struct'};
1092 print "\n\n.. c:type:: " . $name . "\n\n";
1093 } else {
1094 my $name = $args{'struct'};
1095 print "\n\n.. c:struct:: " . $name . "\n\n";
1096 }
988 print_lineno($declaration_start_line);1097 print_lineno($declaration_start_line);
989 $lineprefix = " ";1098 $lineprefix = " ";
990 output_highlight_rst($args{'purpose'});1099 output_highlight_rst($args{'purpose'});
@@ -1043,12 +1152,14 @@ sub output_declaration { · 52 unmodified lines
1043 my $name = shift;1152 my $name = shift;
1044 my $functype = shift;1153 my $functype = shift;
1045 my $func = "output_${functype}_$output_mode";1154 my $func = "output_${functype}_$output_mode";
1155
1156 return if (defined($nosymbol_table{$name}));
1157
1046 if (($output_selection == OUTPUT_ALL) ||1158 if (($output_selection == OUTPUT_ALL) ||
1047 (($output_selection == OUTPUT_INCLUDE ||1159 (($output_selection == OUTPUT_INCLUDE ||
1048 $output_selection == OUTPUT_EXPORTED) &&1160 $output_selection == OUTPUT_EXPORTED) &&
1049 defined($function_table{$name})) ||1161 defined($function_table{$name})) ||
1050 (($output_selection == OUTPUT_EXCLUDE ||1162 ($output_selection == OUTPUT_INTERNAL &&
1051 $output_selection == OUTPUT_INTERNAL) &&
1052 !($functype eq "function" && defined($function_table{$name}))))1163 !($functype eq "function" && defined($function_table{$name}))))
1053 {1164 {
1054 &$func(@_);1165 &$func(@_);
@@ -1229,6 +1340,8 @@ sub show_warnings($$) { · 174 unmodified lines
1229 my $functype = shift;1340 my $functype = shift;
1230 my $name = shift;1341 my $name = shift;
1231 1342
1343 return 0 if (defined($nosymbol_table{$name}));
1344
1232 return 1 if ($output_selection == OUTPUT_ALL);1345 return 1 if ($output_selection == OUTPUT_ALL);
1233 1346
1234 if ($output_selection == OUTPUT_EXPORTED) {1347 if ($output_selection == OUTPUT_EXPORTED) {
@@ -1252,27 +1365,28 @@ sub show_warnings($$) { · 17 unmodified lines
1252 return 0;1365 return 0;
1253 }1366 }
1254 }1367 }
1255 if ($output_selection == OUTPUT_EXCLUDE) {
1256 if (!defined($function_table{$name})) {
1257 return 1;
1258 } else {
1259 return 0;
1260 }
1261 }
1262 die("Please add the new output type at show_warnings()");1368 die("Please add the new output type at show_warnings()");
1263}1369}
1264 1370
1265sub dump_enum($$) {1371sub dump_enum($$) {
1266 my $x = shift;1372 my $x = shift;
1267 my $file = shift;1373 my $file = shift;
1374 my $members;
1375
1268 1376
1269 $x =~ s@/\*.*?\*/@@gos; # strip comments.1377 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1270 # strip #define macros inside enums1378 # strip #define macros inside enums
1271 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;1379 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1272 1380
1273 if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {1381 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1382 $declaration_name = $2;
1383 $members = $1;
1384 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1274 $declaration_name = $1;1385 $declaration_name = $1;
1275 my $members = $2;1386 $members = $2;
1387 }
1388
1389 if ($declaration_name) {
1276 my %_members;1390 my %_members;
1277 1391
1278 $members =~ s/\s+$//;1392 $members =~ s/\s+$//;
@@ -1307,8 +1421,7 @@ sub dump_enum($$) { · 28 unmodified lines
1307 'sections' => \%sections,1421 'sections' => \%sections,
1308 'purpose' => $declaration_purpose1422 'purpose' => $declaration_purpose
1309 });1423 });
1310 }1424 } else {
1311 else {
1312 print STDERR "${file}:$.: error: Cannot parse enum!\n";1425 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1313 ++$errors;1426 ++$errors;
1314 }1427 }
@@ -1403,7 +1516,7 @@ sub create_parameterlist($$$$) { · 88 unmodified lines
1403 # Treat preprocessor directive as a typeless variable just to fill1516 # Treat preprocessor directive as a typeless variable just to fill
1404 # corresponding data structures "correctly". Catch it later in1517 # corresponding data structures "correctly". Catch it later in
1405 # output_* subs.1518 # output_* subs.
1406 push_parameter($arg, "", $file);1519 push_parameter($arg, "", "", $file);
1407 } elsif ($arg =~ m/\(.+\)\s*\(/) {1520 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1408 # pointer-to-function1521 # pointer-to-function
1409 $arg =~ tr/#/,/;1522 $arg =~ tr/#/,/;
@@ -1412,7 +1525,7 @@ sub create_parameterlist($$$$) { · 2 unmodified lines
1412 $type = $arg;1525 $type = $arg;
1413 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;1526 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1414 save_struct_actual($param);1527 save_struct_actual($param);
1415 push_parameter($param, $type, $file, $declaration_name);1528 push_parameter($param, $type, $arg, $file, $declaration_name);
1416 } elsif ($arg) {1529 } elsif ($arg) {
1417 $arg =~ s/\s*:\s*/:/g;1530 $arg =~ s/\s*:\s*/:/g;
1418 $arg =~ s/\s*\[/\[/g;1531 $arg =~ s/\s*\[/\[/g;
@@ -1437,26 +1550,28 @@ sub create_parameterlist($$$$) { · 18 unmodified lines
1437 foreach $param (@args) {1550 foreach $param (@args) {
1438 if ($param =~ m/^(\*+)\s*(.*)/) {1551 if ($param =~ m/^(\*+)\s*(.*)/) {
1439 save_struct_actual($2);1552 save_struct_actual($2);
1440 push_parameter($2, "$type $1", $file, $declaration_name);1553
1554 push_parameter($2, "$type $1", $arg, $file, $declaration_name);
1441 }1555 }
1442 elsif ($param =~ m/(.*?):(\d+)/) {1556 elsif ($param =~ m/(.*?):(\d+)/) {
1443 if ($type ne "") { # skip unnamed bit-fields1557 if ($type ne "") { # skip unnamed bit-fields
1444 save_struct_actual($1);1558 save_struct_actual($1);
1445 push_parameter($1, "$type:$2", $file, $declaration_name)1559 push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
1446 }1560 }
1447 }1561 }
1448 else {1562 else {
1449 save_struct_actual($param);1563 save_struct_actual($param);
1450 push_parameter($param, $type, $file, $declaration_name);1564 push_parameter($param, $type, $arg, $file, $declaration_name);
1451 }1565 }
1452 }1566 }
1453 }1567 }
1454 }1568 }
1455}1569}
1456 1570
1457sub push_parameter($$$$) {1571sub push_parameter($$$$$) {
1458 my $param = shift;1572 my $param = shift;
1459 my $type = shift;1573 my $type = shift;
1574 my $org_arg = shift;
1460 my $file = shift;1575 my $file = shift;
1461 my $declaration_name = shift;1576 my $declaration_name = shift;
1462 1577
@@ -1520,8 +1635,8 @@ sub push_parameter($$$$) { · 57 unmodified lines
1520 # "[blah" in a parameter string;1635 # "[blah" in a parameter string;
1521 ###$param =~ s/\s*//g;1636 ###$param =~ s/\s*//g;
1522 push @parameterlist, $param;1637 push @parameterlist, $param;
1523 $type =~ s/\s\s+/ /g;1638 $org_arg =~ s/\s\s+/ /g;
1524 $parametertypes{$param} = $type;1639 $parametertypes{$param} = $org_arg;
1525}1640}
1526 1641
1527sub check_sections($$$$$) {1642sub check_sections($$$$$) {
@@ -1595,7 +1710,7 @@ sub dump_function($$) { · 67 unmodified lines
1595 my $file = shift;1710 my $file = shift;
1596 my $noret = 0;1711 my $noret = 0;
1597 1712
1598 print_lineno($.);1713 print_lineno($new_start_line);
1599 1714
1600 $prototype =~ s/^static +//;1715 $prototype =~ s/^static +//;
1601 $prototype =~ s/^extern +//;1716 $prototype =~ s/^extern +//;
@@ -1672,30 +1787,48 @@ sub dump_function($$) { · 70 unmodified lines
1672 return;1787 return;
1673 }1788 }
1674 1789
1675 my $prms = join " ", @parameterlist;1790 my $prms = join " ", @parameterlist;
1676 check_sections($file, $declaration_name, "function", $sectcheck, $prms);1791 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1677 1792
1678 # This check emits a lot of warnings at the moment, because many1793 # This check emits a lot of warnings at the moment, because many
1679 # functions don't have a 'Return' doc section. So until the number1794 # functions don't have a 'Return' doc section. So until the number
1680 # of warnings goes sufficiently down, the check is only performed in1795 # of warnings goes sufficiently down, the check is only performed in
1681 # verbose mode.1796 # verbose mode.
1682 # TODO: always perform the check.1797 # TODO: always perform the check.
1683 if ($verbose && !$noret) {1798 if ($verbose && !$noret) {
1684 check_return_section($file, $declaration_name, $return_type);1799 check_return_section($file, $declaration_name, $return_type);
1685 }1800 }
1686 1801
1687 output_declaration($declaration_name,1802 # The function parser can be called with a typedef parameter.
1688 'function',1803 # Handle it.
1689 {'function' => $declaration_name,1804 if ($return_type =~ /typedef/) {
1690 'module' => $modulename,1805 output_declaration($declaration_name,
1691 'functiontype' => $return_type,1806 'function',
1692 'parameterlist' => \@parameterlist,1807 {'function' => $declaration_name,
1693 'parameterdescs' => \%parameterdescs,1808 'typedef' => 1,
1694 'parametertypes' => \%parametertypes,1809 'module' => $modulename,
1695 'sectionlist' => \@sectionlist,1810 'functiontype' => $return_type,
1696 'sections' => \%sections,1811 'parameterlist' => \@parameterlist,
1697 'purpose' => $declaration_purpose1812 'parameterdescs' => \%parameterdescs,
1698 });1813 'parametertypes' => \%parametertypes,
1814 'sectionlist' => \@sectionlist,
1815 'sections' => \%sections,
1816 'purpose' => $declaration_purpose
1817 });
1818 } else {
1819 output_declaration($declaration_name,
1820 'function',
1821 {'function' => $declaration_name,
1822 'module' => $modulename,
1823 'functiontype' => $return_type,
1824 'parameterlist' => \@parameterlist,
1825 'parameterdescs' => \%parameterdescs,
1826 'parametertypes' => \%parametertypes,
1827 'sectionlist' => \@sectionlist,
1828 'sections' => \%sections,
1829 'purpose' => $declaration_purpose
1830 });
1831 }
1699}1832}
1700 1833
1701sub reset_state {1834sub reset_state {
@@ -1873,6 +2006,7 @@ sub process_export_file($) { · 171 unmodified lines
1873 2006
1874 while (<IN>) {2007 while (<IN>) {
1875 if (/$export_symbol/) {2008 if (/$export_symbol/) {
2009 next if (defined($nosymbol_table{$2}));
1876 $function_table{$2} = 1;2010 $function_table{$2} = 1;
1877 }2011 }
1878 }2012 }
@@ -1904,7 +2038,7 @@ sub process_name($$) { · 25 unmodified lines
1904 if (/$doc_block/o) {2038 if (/$doc_block/o) {
1905 $state = STATE_DOCBLOCK;2039 $state = STATE_DOCBLOCK;
1906 $contents = "";2040 $contents = "";
1907 $new_start_line = $. + 1;2041 $new_start_line = $.;
1908 2042
1909 if ( $1 eq "" ) {2043 if ( $1 eq "" ) {
1910 $section = $section_intro;2044 $section = $section_intro;
@@ -1987,6 +2121,7 @@ sub process_body($$) { · 76 unmodified lines
1987 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {2121 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
1988 dump_section($file, $section, $contents);2122 dump_section($file, $section, $contents);
1989 $section = $section_default;2123 $section = $section_default;
2124 $new_start_line = $.;
1990 $contents = "";2125 $contents = "";
1991 }2126 }
1992 2127
@@ -2042,6 +2177,7 @@ sub process_body($$) { · 49 unmodified lines
2042 $prototype = "";2177 $prototype = "";
2043 $state = STATE_PROTO;2178 $state = STATE_PROTO;
2044 $brcount = 0;2179 $brcount = 0;
2180 $new_start_line = $. + 1;
2045 } elsif (/$doc_content/) {2181 } elsif (/$doc_content/) {
2046 if ($1 eq "") {2182 if ($1 eq "") {
2047 if ($section eq $section_context) {2183 if ($section eq $section_context) {
@@ -2189,7 +2325,7 @@ sub process_file($) { · 141 unmodified lines
2189 2325
2190 $file = map_filename($orig_file);2326 $file = map_filename($orig_file);
2191 2327
2192 if (!open(IN,"<$file")) {2328 if (!open(IN_FILE,"<$file")) {
2193 print STDERR "Error: Cannot open file $file\n";2329 print STDERR "Error: Cannot open file $file\n";
2194 ++$errors;2330 ++$errors;
2195 return;2331 return;
@@ -2198,9 +2334,9 @@ sub process_file($) { · 2 unmodified lines
2198 $. = 1;2334 $. = 1;
2199 2335
2200 $section_counter = 0;2336 $section_counter = 0;
2201 while (<IN>) {2337 while (<IN_FILE>) {
2202 while (s/\\\s*$//) {2338 while (s/\\\s*$//) {
2203 $_ .= <IN>;2339 $_ .= <IN_FILE>;
2204 }2340 }
2205 # Replace tabs by spaces2341 # Replace tabs by spaces
2206 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};2342 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
@@ -2232,9 +2368,14 @@ sub process_file($) { · 25 unmodified lines
2232 print STDERR "${file}:1: warning: no structured comments found\n";2368 print STDERR "${file}:1: warning: no structured comments found\n";
2233 }2369 }
2234 }2370 }
2371 close IN_FILE;
2235}2372}
2236 2373
2237 2374
2375if ($output_mode eq "rst") {
2376 get_sphinx_version() if (!$sphinx_major);
2377}
2378
2238$kernelversion = get_kernel_version();2379$kernelversion = get_kernel_version();
2239 2380
2240# generate a sequence of code that will splice in highlighting information2381# generate a sequence of code that will splice in highlighting information