forked from ~ljy/RK356X_SDK_RELEASE

blame | history | patch | commit | commitdiff
hc
2024-12-19 9370bb92b2d16684ee45cf24e879c93c509162da 
 kernel/scripts/kernel-doc
....@@ -56,6 +56,13 @@
5656   -rst			Output reStructuredText format.
5757   -none			Do not output documentation, only warnings.
5858 
59
+Output 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
+
5966 Output selection (mutually exclusive):
6067   -export		Only output documentation for symbols that have been
6168 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
....@@ -66,9 +73,8 @@
6673   -function NAME	Only output documentation for the given function(s)
6774 			or DOC: section title(s). All other functions and DOC:
6875 			sections are ignored. May be specified multiple times.
69
-  -nofunction NAME	Do NOT output documentation for the given function(s);
70
-			only output documentation for the other functions and
71
-			DOC: sections. May be specified multiple times.
76
+  -nosymbol NAME	Exclude the specified symbols from the output
77
+		        documentation. May be specified multiple times.
7278 
7379 Output selection modifiers:
7480   -no-doc-sections	Do not output DOC: sections.
....@@ -81,6 +87,7 @@
8187 Other parameters:
8288   -v			Verbose output, more warnings and other information.
8389   -h			Print this help.
90
+  -Werror		Treat warnings as errors.
8491 
8592 EOF
8693     print $message;
....@@ -212,8 +219,10 @@
212219 my $type_constant = '\b``([^\`]+)``\b';
213220 my $type_constant2 = '\%([-_\w]+)';
214221 my $type_func = '(\w+)\(\)';
215
-my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';
222
+my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
223
+my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
216224 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
225
+my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
217226 my $type_env = '(\$\w+)';
218227 my $type_enum = '\&(enum\s*([_\w]+))';
219228 my $type_struct = '\&(struct\s*([_\w]+))';
....@@ -236,6 +245,7 @@
236245                       [$type_typedef, "\\\\fI\$1\\\\fP"],
237246                       [$type_union, "\\\\fI\$1\\\\fP"],
238247                       [$type_param, "\\\\fI\$1\\\\fP"],
248
+                      [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
239249                       [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
240250                       [$type_fallback, "\\\\fI\$1\\\\fP"]
241251 		     );
....@@ -249,14 +259,15 @@
249259                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
250260                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
251261 		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
252
-                       [$type_func, "\\:c\\:func\\:`\$1()`"],
262
+		       [$type_fp_param2, "**\$1\\\\(\\\\)**"],
263
+                       [$type_func, "\$1()"],
253264                        [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
254265                        [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
255266                        [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
256267                        [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
257268                        # in rst this can refer to any type
258269                        [$type_fallback, "\\:c\\:type\\:`\$1`"],
259
-                       [$type_param, "**\$1**"]
270
+                       [$type_param_ref, "**\$1\$2**"]
260271 		      );
261272 my $blankline_rst = "\n";
262273 
....@@ -266,9 +277,12 @@
266277 }
267278 
268279 my $kernelversion;
280
+my ($sphinx_major, $sphinx_minor, $sphinx_patch);
281
+
269282 my $dohighlight = "";
270283 
271284 my $verbose = 0;
285
+my $Werror = 0;
272286 my $output_mode = "rst";
273287 my $output_preformatted = 0;
274288 my $no_doc_sections = 0;
....@@ -280,12 +294,11 @@
280294 use constant {
281295     OUTPUT_ALL          => 0, # output all symbols and doc sections
282296     OUTPUT_INCLUDE      => 1, # output only specified symbols
283
-    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
284
-    OUTPUT_EXPORTED     => 3, # output exported symbols
285
-    OUTPUT_INTERNAL     => 4, # output non-exported symbols
297
+    OUTPUT_EXPORTED     => 2, # output exported symbols
298
+    OUTPUT_INTERNAL     => 3, # output non-exported symbols
286299 };
287300 my $output_selection = OUTPUT_ALL;
288
-my $show_not_found = 0;
301
+my $show_not_found = 0;	# No longer used
289302 
290303 my @export_file_list;
291304 
....@@ -307,6 +320,7 @@
307320 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
308321 # could cause "use of undefined value" or other bugs.
309322 my ($function, %function_table, %parametertypes, $declaration_purpose);
323
+my %nosymbol_table = ();
310324 my $declaration_start_line;
311325 my ($type, $declaration_name, $return_type);
312326 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
....@@ -315,9 +329,21 @@
315329 	$verbose = "$ENV{'KBUILD_VERBOSE'}";
316330 }
317331 
332
+if (defined($ENV{'KDOC_WERROR'})) {
333
+	$Werror = "$ENV{'KDOC_WERROR'}";
334
+}
335
+
336
+if (defined($ENV{'KCFLAGS'})) {
337
+	my $kcflags = "$ENV{'KCFLAGS'}";
338
+
339
+	if ($kcflags =~ /Werror/) {
340
+		$Werror = 1;
341
+	}
342
+}
343
+
318344 # Generated docbook code is inserted in a template at a point where
319345 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
320
-# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
346
+# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
321347 # We keep track of number of generated entries and generate a dummy
322348 # if needs be to ensure the expanded template can be postprocessed
323349 # into html.
....@@ -327,13 +353,14 @@
327353 
328354 # Parser states
329355 use constant {
330
-    STATE_NORMAL        => 0, # normal code
331
-    STATE_NAME          => 1, # looking for function name
332
-    STATE_BODY_MAYBE    => 2, # body - or maybe more description
333
-    STATE_BODY          => 3, # the body of the comment
334
-    STATE_PROTO         => 4, # scanning prototype
335
-    STATE_DOCBLOCK      => 5, # documentation block
336
-    STATE_INLINE        => 6, # gathering documentation outside main block
356
+    STATE_NORMAL        => 0,        # normal code
357
+    STATE_NAME          => 1,        # looking for function name
358
+    STATE_BODY_MAYBE    => 2,        # body - or maybe more description
359
+    STATE_BODY          => 3,        # the body of the comment
360
+    STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
361
+    STATE_PROTO         => 5,        # scanning prototype
362
+    STATE_DOCBLOCK      => 6,        # documentation block
363
+    STATE_INLINE        => 7,        # gathering doc outside main block
337364 };
338365 my $state;
339366 my $in_doc_sect;
....@@ -361,7 +388,7 @@
361388 my $doc_com_body = '\s*\* ?';
362389 my $doc_decl = $doc_com . '(\w+)';
363390 # @params and a strictly limited set of supported section names
364
-my $doc_sect = $doc_com . 
391
+my $doc_sect = $doc_com .
365392     '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
366393 my $doc_content = $doc_com_body . '(.*)';
367394 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
....@@ -413,10 +440,9 @@
413440 	$output_selection = OUTPUT_INCLUDE;
414441 	$function = shift @ARGV;
415442 	$function_table{$function} = 1;
416
-    } elsif ($cmd eq "nofunction") { # output all except specific functions
417
-	$output_selection = OUTPUT_EXCLUDE;
418
-	$function = shift @ARGV;
419
-	$function_table{$function} = 1;
443
+    } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
444
+	my $symbol = shift @ARGV;
445
+	$nosymbol_table{$symbol} = 1;
420446     } elsif ($cmd eq "export") { # only exported symbols
421447 	$output_selection = OUTPUT_EXPORTED;
422448 	%function_table = ();
....@@ -428,6 +454,8 @@
428454 	push(@export_file_list, $file);
429455     } elsif ($cmd eq "v") {
430456 	$verbose = 1;
457
+    } elsif ($cmd eq "Werror") {
458
+	$Werror = 1;
431459     } elsif (($cmd eq "h") || ($cmd eq "help")) {
432460 	usage();
433461     } elsif ($cmd eq 'no-doc-sections') {
....@@ -435,7 +463,24 @@
435463     } elsif ($cmd eq 'enable-lineno') {
436464 	    $enable_lineno = 1;
437465     } elsif ($cmd eq 'show-not-found') {
438
-	$show_not_found = 1;
466
+	$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
+	}
439484     } else {
440485 	# Unknown argument
441486         usage();
....@@ -443,6 +488,51 @@
443488 }
444489 
445490 # continue execution near EOF;
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.
494
+sub findprog($)
495
+{
496
+	foreach(split(/:/, $ENV{PATH})) {
497
+		return "$_/$_[0]" if(-x "$_/$_[0]");
498
+	}
499
+}
500
+
501
+sub 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
+}
446536 
447537 # get kernel version from env
448538 sub get_kernel_version() {
....@@ -510,11 +600,11 @@
510600         return;
511601     }
512602 
603
+    return if (defined($nosymbol_table{$name}));
604
+
513605     if (($output_selection == OUTPUT_ALL) ||
514
-	($output_selection == OUTPUT_INCLUDE &&
515
-	 defined($function_table{$name})) ||
516
-	($output_selection == OUTPUT_EXCLUDE &&
517
-	 !defined($function_table{$name})))
606
+	(($output_selection == OUTPUT_INCLUDE) &&
607
+	 defined($function_table{$name})))
518608     {
519609 	dump_section($file, $name, $contents);
520610 	output_blockhead({'sectionlist' => \@sectionlist,
....@@ -597,10 +687,10 @@
597687 	$type = $args{'parametertypes'}{$parameter};
598688 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
599689 	    # pointer-to-function
600
-	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
690
+	    print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
601691 	} else {
602692 	    $type =~ s/([^\*])$/$1 /;
603
-	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
693
+	    print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
604694 	}
605695 	$count++;
606696 	$parenth = "";
....@@ -740,6 +830,8 @@
740830     my ($parameter, $section);
741831 
742832     foreach $section (@{$args{'sectionlist'}}) {
833
+	next if (defined($nosymbol_table{$section}));
834
+
743835 	if ($output_selection != OUTPUT_INCLUDE) {
744836 	    print "**$section**\n\n";
745837 	}
....@@ -751,7 +843,7 @@
751843 
752844 #
753845 # Apply the RST highlights to a sub-block of text.
754
-#   
846
+#
755847 sub highlight_block($) {
756848     # The dohighlight kludge requires the text be called $contents
757849     my $contents = shift;
....@@ -825,16 +917,37 @@
825917     my ($parameter, $section);
826918     my $oldprefix = $lineprefix;
827919     my $start = "";
920
+    my $is_macro = 0;
828921 
829
-    if ($args{'typedef'}) {
830
-	print ".. c:type:: ". $args{'function'} . "\n\n";
831
-	print_lineno($declaration_start_line);
832
-	print "   **Typedef**: ";
833
-	$lineprefix = "";
834
-	output_highlight_rst($args{'purpose'});
835
-	$start = "\n\n**Syntax**\n\n  ``";
922
+    if ($sphinx_major < 3) {
923
+	if ($args{'typedef'}) {
924
+	    print ".. c:type:: ". $args{'function'} . "\n\n";
925
+	    print_lineno($declaration_start_line);
926
+	    print "   **Typedef**: ";
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
+	}
836934     } else {
837
-	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
+	}
838951     }
839952     if ($args{'functiontype'} ne "") {
840953 	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
....@@ -853,15 +966,17 @@
853966 
854967 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
855968 	    # pointer-to-function
856
-	    print $1 . $parameter . ") (" . $2;
969
+	    print $1 . $parameter . ") (" . $2 . ")";
857970 	} else {
858
-	    print $type . " " . $parameter;
971
+	    print $type;
859972 	}
860973     }
861
-    if ($args{'typedef'}) {
862
-	print ");``\n\n";
974
+    if ($is_macro) {
975
+	print ")``\n\n";
863976     } else {
864977 	print ")\n\n";
978
+    }
979
+    if (!$args{'typedef'}) {
865980 	print_lineno($declaration_start_line);
866981 	$lineprefix = "   ";
867982 	output_highlight_rst($args{'purpose'});
....@@ -876,7 +991,7 @@
876991 	$type = $args{'parametertypes'}{$parameter};
877992 
878993 	if ($type ne "") {
879
-	    print "``$type $parameter``\n";
994
+	    print "``$type``\n";
880995 	} else {
881996 	    print "``$parameter``\n";
882997 	}
....@@ -917,9 +1032,14 @@
9171032     my ($parameter);
9181033     my $oldprefix = $lineprefix;
9191034     my $count;
920
-    my $name = "enum " . $args{'enum'};
9211035 
922
-    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
+    }
9231043     print_lineno($declaration_start_line);
9241044     $lineprefix = "   ";
9251045     output_highlight_rst($args{'purpose'});
....@@ -945,8 +1065,13 @@
9451065     my %args = %{$_[0]};
9461066     my ($parameter);
9471067     my $oldprefix = $lineprefix;
948
-    my $name = "typedef " . $args{'typedef'};
1068
+    my $name;
9491069 
1070
+    if ($sphinx_major < 3) {
1071
+	$name = "typedef " . $args{'typedef'};
1072
+    } else {
1073
+	$name = $args{'typedef'};
1074
+    }
9501075     print "\n\n.. c:type:: " . $name . "\n\n";
9511076     print_lineno($declaration_start_line);
9521077     $lineprefix = "   ";
....@@ -961,9 +1086,18 @@
9611086     my %args = %{$_[0]};
9621087     my ($parameter);
9631088     my $oldprefix = $lineprefix;
964
-    my $name = $args{'type'} . " " . $args{'struct'};
9651089 
966
-    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
+	if ($args{'type'} eq 'union') {
1096
+	    print "\n\n.. c:union:: " . $name . "\n\n";
1097
+	} else {
1098
+	    print "\n\n.. c:struct:: " . $name . "\n\n";
1099
+	}
1100
+    }
9671101     print_lineno($declaration_start_line);
9681102     $lineprefix = "   ";
9691103     output_highlight_rst($args{'purpose'});
....@@ -1022,12 +1156,14 @@
10221156     my $name = shift;
10231157     my $functype = shift;
10241158     my $func = "output_${functype}_$output_mode";
1159
+
1160
+    return if (defined($nosymbol_table{$name}));
1161
+
10251162     if (($output_selection == OUTPUT_ALL) ||
10261163 	(($output_selection == OUTPUT_INCLUDE ||
10271164 	  $output_selection == OUTPUT_EXPORTED) &&
10281165 	 defined($function_table{$name})) ||
1029
-	(($output_selection == OUTPUT_EXCLUDE ||
1030
-	  $output_selection == OUTPUT_INTERNAL) &&
1166
+	($output_selection == OUTPUT_INTERNAL &&
10311167 	 !($functype eq "function" && defined($function_table{$name}))))
10321168     {
10331169 	&$func(@_);
....@@ -1062,7 +1198,7 @@
10621198     my $x = shift;
10631199     my $file = shift;
10641200 
1065
-    if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}/) {
1201
+    if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
10661202 	my $decl_type = $1;
10671203 	$declaration_name = $2;
10681204 	my $members = $3;
....@@ -1073,10 +1209,22 @@
10731209 	# strip comments:
10741210 	$members =~ s/\/\*.*?\*\///gos;
10751211 	# strip attributes
1076
-	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1077
-	$members =~ s/__aligned\s*\([^;]*\)//gos;
1078
-	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
1212
+	$members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1213
+	$members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1214
+	$members =~ s/\s*__packed\s*/ /gos;
1215
+	$members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1216
+	$members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1217
+	$members =~ s/\s*____cacheline_aligned/ /gos;
1218
+	# unwrap struct_group():
1219
+	# - first eat non-declaration parameters and rewrite for final match
1220
+	# - then remove macro, outer parens, and trailing semicolon
1221
+	$members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
1222
+	$members =~ s/\bstruct_group_(attr|tagged)\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
1223
+	$members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
1224
+	$members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
1225
+
10791226 	# replace DECLARE_BITMAP
1227
+	$members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
10801228 	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
10811229 	# replace DECLARE_HASHTABLE
10821230 	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
....@@ -1203,6 +1351,8 @@
12031351 	my $functype = shift;
12041352 	my $name = shift;
12051353 
1354
+	return 0 if (defined($nosymbol_table{$name}));
1355
+
12061356 	return 1 if ($output_selection == OUTPUT_ALL);
12071357 
12081358 	if ($output_selection == OUTPUT_EXPORTED) {
....@@ -1226,27 +1376,28 @@
12261376 			return 0;
12271377 		}
12281378 	}
1229
-	if ($output_selection == OUTPUT_EXCLUDE) {
1230
-		if (!defined($function_table{$name})) {
1231
-			return 1;
1232
-		} else {
1233
-			return 0;
1234
-		}
1235
-	}
12361379 	die("Please add the new output type at show_warnings()");
12371380 }
12381381 
12391382 sub dump_enum($$) {
12401383     my $x = shift;
12411384     my $file = shift;
1385
+    my $members;
1386
+
12421387 
12431388     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
12441389     # strip #define macros inside enums
12451390     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
12461391 
1247
-    if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) {
1392
+    if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1393
+	$declaration_name = $2;
1394
+	$members = $1;
1395
+    } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
12481396 	$declaration_name = $1;
1249
-	my $members = $2;
1397
+	$members = $2;
1398
+    }
1399
+
1400
+    if ($members) {
12501401 	my %_members;
12511402 
12521403 	$members =~ s/\s+$//;
....@@ -1281,12 +1432,18 @@
12811432 			    'sections' => \%sections,
12821433 			    'purpose' => $declaration_purpose
12831434 			   });
1284
-    }
1285
-    else {
1435
+    } else {
12861436 	print STDERR "${file}:$.: error: Cannot parse enum!\n";
12871437 	++$errors;
12881438     }
12891439 }
1440
+
1441
+my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
1442
+my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
1443
+my $typedef_args = qr { \s*\((.*)\); }x;
1444
+
1445
+my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
1446
+my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
12901447 
12911448 sub dump_typedef($$) {
12921449     my $x = shift;
....@@ -1294,14 +1451,12 @@
12941451 
12951452     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
12961453 
1297
-    # Parse function prototypes
1298
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
1299
-	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
1300
-
1301
-	# Function typedefs
1454
+    # Parse function typedef prototypes
1455
+    if ($x =~ $typedef1 || $x =~ $typedef2) {
13021456 	$return_type = $1;
13031457 	$declaration_name = $2;
13041458 	my $args = $3;
1459
+	$return_type =~ s/^\s+//;
13051460 
13061461 	create_parameterlist($args, ',', $file, $declaration_name);
13071462 
....@@ -1377,7 +1532,7 @@
13771532 	    # Treat preprocessor directive as a typeless variable just to fill
13781533 	    # corresponding data structures "correctly". Catch it later in
13791534 	    # output_* subs.
1380
-	    push_parameter($arg, "", $file);
1535
+	    push_parameter($arg, "", "", $file);
13811536 	} elsif ($arg =~ m/\(.+\)\s*\(/) {
13821537 	    # pointer-to-function
13831538 	    $arg =~ tr/#/,/;
....@@ -1386,7 +1541,7 @@
13861541 	    $type = $arg;
13871542 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
13881543 	    save_struct_actual($param);
1389
-	    push_parameter($param, $type, $file, $declaration_name);
1544
+	    push_parameter($param, $type, $arg, $file, $declaration_name);
13901545 	} elsif ($arg) {
13911546 	    $arg =~ s/\s*:\s*/:/g;
13921547 	    $arg =~ s/\s*\[/\[/g;
....@@ -1411,26 +1566,28 @@
14111566 	    foreach $param (@args) {
14121567 		if ($param =~ m/^(\*+)\s*(.*)/) {
14131568 		    save_struct_actual($2);
1414
-		    push_parameter($2, "$type $1", $file, $declaration_name);
1569
+
1570
+		    push_parameter($2, "$type $1", $arg, $file, $declaration_name);
14151571 		}
14161572 		elsif ($param =~ m/(.*?):(\d+)/) {
14171573 		    if ($type ne "") { # skip unnamed bit-fields
14181574 			save_struct_actual($1);
1419
-			push_parameter($1, "$type:$2", $file, $declaration_name)
1575
+			push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
14201576 		    }
14211577 		}
14221578 		else {
14231579 		    save_struct_actual($param);
1424
-		    push_parameter($param, $type, $file, $declaration_name);
1580
+		    push_parameter($param, $type, $arg, $file, $declaration_name);
14251581 		}
14261582 	    }
14271583 	}
14281584     }
14291585 }
14301586 
1431
-sub push_parameter($$$$) {
1587
+sub push_parameter($$$$$) {
14321588 	my $param = shift;
14331589 	my $type = shift;
1590
+	my $org_arg = shift;
14341591 	my $file = shift;
14351592 	my $declaration_name = shift;
14361593 
....@@ -1447,6 +1604,10 @@
14471604 	    if (!$param =~ /\w\.\.\.$/) {
14481605 	      # handles unnamed variable parameters
14491606 	      $param = "...";
1607
+	    }
1608
+	    elsif ($param =~ /\w\.\.\.$/) {
1609
+	      # for named variable parameters of the form `x...`, remove the dots
1610
+	      $param =~ s/\.\.\.$//;
14501611 	    }
14511612 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
14521613 		$parameterdescs{$param} = "variable arguments";
....@@ -1473,7 +1634,7 @@
14731634 	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
14741635 		$parameterdescs{$param} = $undescribed;
14751636 
1476
-	        if (show_warnings($type, $declaration_name)) {
1637
+	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
14771638 			print STDERR
14781639 			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
14791640 			++$warnings;
....@@ -1490,8 +1651,8 @@
14901651 	# "[blah" in a parameter string;
14911652 	###$param =~ s/\s*//g;
14921653 	push @parameterlist, $param;
1493
-	$type =~ s/\s\s+/ /g;
1494
-	$parametertypes{$param} = $type;
1654
+	$org_arg =~ s/\s\s+/ /g;
1655
+	$parametertypes{$param} = $org_arg;
14951656 }
14961657 
14971658 sub check_sections($$$$$) {
....@@ -1565,6 +1726,8 @@
15651726     my $file = shift;
15661727     my $noret = 0;
15671728 
1729
+    print_lineno($new_start_line);
1730
+
15681731     $prototype =~ s/^static +//;
15691732     $prototype =~ s/^extern +//;
15701733     $prototype =~ s/^asmlinkage +//;
....@@ -1579,6 +1742,7 @@
15791742     $prototype =~ s/__must_check +//;
15801743     $prototype =~ s/__weak +//;
15811744     $prototype =~ s/__sched +//;
1745
+    $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
15821746     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
15831747     $prototype =~ s/__attribute__\s*\(\(
15841748             (?:
....@@ -1639,30 +1803,48 @@
16391803 	return;
16401804     }
16411805 
1642
-	my $prms = join " ", @parameterlist;
1643
-	check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1806
+    my $prms = join " ", @parameterlist;
1807
+    check_sections($file, $declaration_name, "function", $sectcheck, $prms);
16441808 
1645
-        # This check emits a lot of warnings at the moment, because many
1646
-        # functions don't have a 'Return' doc section. So until the number
1647
-        # of warnings goes sufficiently down, the check is only performed in
1648
-        # verbose mode.
1649
-        # TODO: always perform the check.
1650
-        if ($verbose && !$noret) {
1651
-                check_return_section($file, $declaration_name, $return_type);
1652
-        }
1809
+    # This check emits a lot of warnings at the moment, because many
1810
+    # functions don't have a 'Return' doc section. So until the number
1811
+    # of warnings goes sufficiently down, the check is only performed in
1812
+    # verbose mode.
1813
+    # TODO: always perform the check.
1814
+    if ($verbose && !$noret) {
1815
+	    check_return_section($file, $declaration_name, $return_type);
1816
+    }
16531817 
1654
-    output_declaration($declaration_name,
1655
-		       'function',
1656
-		       {'function' => $declaration_name,
1657
-			'module' => $modulename,
1658
-			'functiontype' => $return_type,
1659
-			'parameterlist' => \@parameterlist,
1660
-			'parameterdescs' => \%parameterdescs,
1661
-			'parametertypes' => \%parametertypes,
1662
-			'sectionlist' => \@sectionlist,
1663
-			'sections' => \%sections,
1664
-			'purpose' => $declaration_purpose
1665
-		       });
1818
+    # The function parser can be called with a typedef parameter.
1819
+    # Handle it.
1820
+    if ($return_type =~ /typedef/) {
1821
+	output_declaration($declaration_name,
1822
+			   'function',
1823
+			   {'function' => $declaration_name,
1824
+			    'typedef' => 1,
1825
+			    'module' => $modulename,
1826
+			    'functiontype' => $return_type,
1827
+			    'parameterlist' => \@parameterlist,
1828
+			    'parameterdescs' => \%parameterdescs,
1829
+			    'parametertypes' => \%parametertypes,
1830
+			    'sectionlist' => \@sectionlist,
1831
+			    'sections' => \%sections,
1832
+			    'purpose' => $declaration_purpose
1833
+			   });
1834
+    } else {
1835
+	output_declaration($declaration_name,
1836
+			   'function',
1837
+			   {'function' => $declaration_name,
1838
+			    'module' => $modulename,
1839
+			    'functiontype' => $return_type,
1840
+			    'parameterlist' => \@parameterlist,
1841
+			    'parameterdescs' => \%parameterdescs,
1842
+			    'parametertypes' => \%parametertypes,
1843
+			    'sectionlist' => \@sectionlist,
1844
+			    'sections' => \%sections,
1845
+			    'purpose' => $declaration_purpose
1846
+			   });
1847
+    }
16661848 }
16671849 
16681850 sub reset_state {
....@@ -1757,6 +1939,11 @@
17571939 	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
17581940 	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
17591941 	$prototype =~ s@^\s+@@gos; # strip leading spaces
1942
+
1943
+	 # Handle prototypes for function pointers like:
1944
+	 # int (*pcs_config)(struct foo)
1945
+	$prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
1946
+
17601947 	if ($prototype =~ /SYSCALL_DEFINE/) {
17611948 		syscall_munge();
17621949 	}
....@@ -1835,6 +2022,7 @@
18352022 
18362023     while (<IN>) {
18372024 	if (/$export_symbol/) {
2025
+	    next if (defined($nosymbol_table{$2}));
18382026 	    $function_table{$2} = 1;
18392027 	}
18402028     }
....@@ -1866,7 +2054,7 @@
18662054     if (/$doc_block/o) {
18672055 	$state = STATE_DOCBLOCK;
18682056 	$contents = "";
1869
-	$new_start_line = $. + 1;
2057
+	$new_start_line = $.;
18702058 
18712059 	if ( $1 eq "" ) {
18722060 	    $section = $section_intro;
....@@ -1904,13 +2092,13 @@
19042092 	    ++$warnings;
19052093 	}
19062094 
1907
-	if ($identifier =~ m/^struct/) {
2095
+	if ($identifier =~ m/^struct\b/) {
19082096 	    $decl_type = 'struct';
1909
-	} elsif ($identifier =~ m/^union/) {
2097
+	} elsif ($identifier =~ m/^union\b/) {
19102098 	    $decl_type = 'union';
1911
-	} elsif ($identifier =~ m/^enum/) {
2099
+	} elsif ($identifier =~ m/^enum\b/) {
19122100 	    $decl_type = 'enum';
1913
-	} elsif ($identifier =~ m/^typedef/) {
2101
+	} elsif ($identifier =~ m/^typedef\b/) {
19142102 	    $decl_type = 'typedef';
19152103 	} else {
19162104 	    $decl_type = 'function';
....@@ -1933,6 +2121,25 @@
19332121 #
19342122 sub process_body($$) {
19352123     my $file = shift;
2124
+
2125
+    # Until all named variable macro parameters are
2126
+    # documented using the bare name (`x`) rather than with
2127
+    # dots (`x...`), strip the dots:
2128
+    if ($section =~ /\w\.\.\.$/) {
2129
+	$section =~ s/\.\.\.$//;
2130
+
2131
+	if ($verbose) {
2132
+	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
2133
+	    ++$warnings;
2134
+	}
2135
+    }
2136
+
2137
+    if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2138
+	dump_section($file, $section, $contents);
2139
+	$section = $section_default;
2140
+	$new_start_line = $.;
2141
+	$contents = "";
2142
+    }
19362143 
19372144     if (/$doc_sect/i) { # case insensitive for supported section names
19382145 	$newsection = $1;
....@@ -1986,19 +2193,23 @@
19862193 	$prototype = "";
19872194 	$state = STATE_PROTO;
19882195 	$brcount = 0;
2196
+        $new_start_line = $. + 1;
19892197     } elsif (/$doc_content/) {
1990
-	# miguel-style comment kludge, look for blank lines after
1991
-	# @parameter line to signify start of description
19922198 	if ($1 eq "") {
1993
-	    if ($section =~ m/^@/ || $section eq $section_context) {
2199
+	    if ($section eq $section_context) {
19942200 		dump_section($file, $section, $contents);
19952201 		$section = $section_default;
19962202 		$contents = "";
19972203 		$new_start_line = $.;
2204
+		$state = STATE_BODY;
19982205 	    } else {
2206
+		if ($section ne $section_default) {
2207
+		    $state = STATE_BODY_WITH_BLANK_LINE;
2208
+		} else {
2209
+		    $state = STATE_BODY;
2210
+		}
19992211 		$contents .= "\n";
20002212 	    }
2001
-	    $state = STATE_BODY;
20022213 	} elsif ($state == STATE_BODY_MAYBE) {
20032214 	    # Continued declaration purpose
20042215 	    chomp($declaration_purpose);
....@@ -2130,7 +2341,7 @@
21302341 
21312342     $file = map_filename($orig_file);
21322343 
2133
-    if (!open(IN,"<$file")) {
2344
+    if (!open(IN_FILE,"<$file")) {
21342345 	print STDERR "Error: Cannot open file $file\n";
21352346 	++$errors;
21362347 	return;
....@@ -2139,9 +2350,9 @@
21392350     $. = 1;
21402351 
21412352     $section_counter = 0;
2142
-    while (<IN>) {
2353
+    while (<IN_FILE>) {
21432354 	while (s/\\\s*$//) {
2144
-	    $_ .= <IN>;
2355
+	    $_ .= <IN_FILE>;
21452356 	}
21462357 	# Replace tabs by spaces
21472358         while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
....@@ -2150,7 +2361,8 @@
21502361 	    process_normal();
21512362 	} elsif ($state == STATE_NAME) {
21522363 	    process_name($file, $_);
2153
-	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
2364
+	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
2365
+		 $state == STATE_BODY_WITH_BLANK_LINE) {
21542366 	    process_body($file, $_);
21552367 	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
21562368 	    process_inline($file, $_);
....@@ -2162,16 +2374,23 @@
21622374     }
21632375 
21642376     # Make sure we got something interesting.
2165
-    if ($initial_section_counter == $section_counter) {
2166
-	if ($output_mode ne "none") {
2377
+    if ($initial_section_counter == $section_counter && $
2378
+	output_mode ne "none") {
2379
+	if ($output_selection == OUTPUT_INCLUDE) {
2380
+	    print STDERR "${file}:1: warning: '$_' not found\n"
2381
+		for keys %function_table;
2382
+	}
2383
+	else {
21672384 	    print STDERR "${file}:1: warning: no structured comments found\n";
21682385 	}
2169
-	if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2170
-	    print STDERR "    Was looking for '$_'.\n" for keys %function_table;
2171
-	}
21722386     }
2387
+    close IN_FILE;
21732388 }
21742389 
2390
+
2391
+if ($output_mode eq "rst") {
2392
+	get_sphinx_version() if (!$sphinx_major);
2393
+}
21752394 
21762395 $kernelversion = get_kernel_version();
21772396 
....@@ -2219,4 +2438,9 @@
22192438   print STDERR "$warnings warnings\n";
22202439 }
22212440 
2222
-exit($output_mode eq "none" ? 0 : $errors);
2441
+if ($Werror && $warnings) {
2442
+    print STDERR "$warnings warnings as Errors\n";
2443
+    exit($warnings);
2444
+} else {
2445
+    exit($output_mode eq "none" ? 0 : $errors)
2446
+}