kernel-doc (dbe8ba00e5adc7573b8a91855f28a383c9728991) kernel-doc (eab795ddd84ffdb1c67250062d01a81be20bb208)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 52 unchanged lines hidden (view full) ---

61 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
62 in any input FILE or -export-file FILE.
63 -internal Only output documentation for symbols that have NOT been
64 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
65 in any input FILE or -export-file FILE.
66 -function NAME Only output documentation for the given function(s)
67 or DOC: section title(s). All other functions and DOC:
68 sections are ignored. May be specified multiple times.
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 52 unchanged lines hidden (view full) ---

61 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
62 in any input FILE or -export-file FILE.
63 -internal Only output documentation for symbols that have NOT been
64 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
65 in any input FILE or -export-file FILE.
66 -function NAME Only output documentation for the given function(s)
67 or DOC: section title(s). All other functions and DOC:
68 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.
69 -nosymbol NAME Exclude the specified symbols from the output
70 documentation. May be specified multiple times.
72
73Output selection modifiers:
74 -no-doc-sections Do not output DOC: sections.
75 -enable-lineno Enable output of #define LINENO lines. Only works with
76 reStructuredText format.
77 -export-file FILE Specify an additional FILE in which to look for
78 EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
79 -export or -internal. May be specified multiple times.

--- 203 unchanged lines hidden (view full) ---

283my $enable_lineno = 0;
284my @highlights = @highlights_rst;
285my $blankline = $blankline_rst;
286my $modulename = "Kernel API";
287
288use constant {
289 OUTPUT_ALL => 0, # output all symbols and doc sections
290 OUTPUT_INCLUDE => 1, # output only specified symbols
71
72Output selection modifiers:
73 -no-doc-sections Do not output DOC: sections.
74 -enable-lineno Enable output of #define LINENO lines. Only works with
75 reStructuredText format.
76 -export-file FILE Specify an additional FILE in which to look for
77 EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
78 -export or -internal. May be specified multiple times.

--- 203 unchanged lines hidden (view full) ---

282my $enable_lineno = 0;
283my @highlights = @highlights_rst;
284my $blankline = $blankline_rst;
285my $modulename = "Kernel API";
286
287use constant {
288 OUTPUT_ALL => 0, # output all symbols and doc sections
289 OUTPUT_INCLUDE => 1, # output only specified symbols
291 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
292 OUTPUT_EXPORTED => 3, # output exported symbols
293 OUTPUT_INTERNAL => 4, # output non-exported symbols
290 OUTPUT_EXPORTED => 2, # output exported symbols
291 OUTPUT_INTERNAL => 3, # output non-exported symbols
294};
295my $output_selection = OUTPUT_ALL;
296my $show_not_found = 0; # No longer used
297
298my @export_file_list;
299
300my @build_time;
301if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&

--- 8 unchanged lines hidden (view full) ---

310 'November', 'December')[$build_time[4]] .
311 " " . ($build_time[5]+1900);
312
313# Essentially these are globals.
314# They probably want to be tidied up, made more localised or something.
315# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
316# could cause "use of undefined value" or other bugs.
317my ($function, %function_table, %parametertypes, $declaration_purpose);
292};
293my $output_selection = OUTPUT_ALL;
294my $show_not_found = 0; # No longer used
295
296my @export_file_list;
297
298my @build_time;
299if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&

--- 8 unchanged lines hidden (view full) ---

308 'November', 'December')[$build_time[4]] .
309 " " . ($build_time[5]+1900);
310
311# Essentially these are globals.
312# They probably want to be tidied up, made more localised or something.
313# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
314# could cause "use of undefined value" or other bugs.
315my ($function, %function_table, %parametertypes, $declaration_purpose);
316my %nosymbol_table = ();
318my $declaration_start_line;
319my ($type, $declaration_name, $return_type);
320my ($newsection, $newcontents, $prototype, $brcount, %source_map);
321
322if (defined($ENV{'KBUILD_VERBOSE'})) {
323 $verbose = "$ENV{'KBUILD_VERBOSE'}";
324}
325

--- 103 unchanged lines hidden (view full) ---

429 } elsif ($cmd eq "none") {
430 $output_mode = "none";
431 } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
432 $modulename = shift @ARGV;
433 } elsif ($cmd eq "function") { # to only output specific functions
434 $output_selection = OUTPUT_INCLUDE;
435 $function = shift @ARGV;
436 $function_table{$function} = 1;
317my $declaration_start_line;
318my ($type, $declaration_name, $return_type);
319my ($newsection, $newcontents, $prototype, $brcount, %source_map);
320
321if (defined($ENV{'KBUILD_VERBOSE'})) {
322 $verbose = "$ENV{'KBUILD_VERBOSE'}";
323}
324

--- 103 unchanged lines hidden (view full) ---

428 } elsif ($cmd eq "none") {
429 $output_mode = "none";
430 } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
431 $modulename = shift @ARGV;
432 } elsif ($cmd eq "function") { # to only output specific functions
433 $output_selection = OUTPUT_INCLUDE;
434 $function = shift @ARGV;
435 $function_table{$function} = 1;
437 } elsif ($cmd eq "nofunction") { # output all except specific functions
438 $output_selection = OUTPUT_EXCLUDE;
439 $function = shift @ARGV;
440 $function_table{$function} = 1;
436 } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
437 my $symbol = shift @ARGV;
438 $nosymbol_table{$symbol} = 1;
441 } elsif ($cmd eq "export") { # only exported symbols
442 $output_selection = OUTPUT_EXPORTED;
443 %function_table = ();
444 } elsif ($cmd eq "internal") { # only non-exported symbols
445 $output_selection = OUTPUT_INTERNAL;
446 %function_table = ();
447 } elsif ($cmd eq "export-file") {
448 my $file = shift @ARGV;

--- 116 unchanged lines hidden (view full) ---

565 my $file = shift;
566 my $name = shift;
567 my $contents = join "\n", @_;
568
569 if ($no_doc_sections) {
570 return;
571 }
572
439 } elsif ($cmd eq "export") { # only exported symbols
440 $output_selection = OUTPUT_EXPORTED;
441 %function_table = ();
442 } elsif ($cmd eq "internal") { # only non-exported symbols
443 $output_selection = OUTPUT_INTERNAL;
444 %function_table = ();
445 } elsif ($cmd eq "export-file") {
446 my $file = shift @ARGV;

--- 116 unchanged lines hidden (view full) ---

563 my $file = shift;
564 my $name = shift;
565 my $contents = join "\n", @_;
566
567 if ($no_doc_sections) {
568 return;
569 }
570
571 return if (defined($nosymbol_table{$name}));
572
573 if (($output_selection == OUTPUT_ALL) ||
573 if (($output_selection == OUTPUT_ALL) ||
574 ($output_selection == OUTPUT_INCLUDE &&
575 defined($function_table{$name})) ||
576 ($output_selection == OUTPUT_EXCLUDE &&
577 !defined($function_table{$name})))
574 (($output_selection == OUTPUT_INCLUDE) &&
575 defined($function_table{$name})))
578 {
579 dump_section($file, $name, $contents);
580 output_blockhead({'sectionlist' => \@sectionlist,
581 'sections' => \%sections,
582 'module' => $modulename,
583 'content-only' => ($output_selection != OUTPUT_ALL), });
584 }
585}

--- 209 unchanged lines hidden (view full) ---

795# starts by putting out the name of the doc section itself, but that tends
796# to duplicate a header already in the template file.
797#
798sub output_blockhead_rst(%) {
799 my %args = %{$_[0]};
800 my ($parameter, $section);
801
802 foreach $section (@{$args{'sectionlist'}}) {
576 {
577 dump_section($file, $name, $contents);
578 output_blockhead({'sectionlist' => \@sectionlist,
579 'sections' => \%sections,
580 'module' => $modulename,
581 'content-only' => ($output_selection != OUTPUT_ALL), });
582 }
583}

--- 209 unchanged lines hidden (view full) ---

793# starts by putting out the name of the doc section itself, but that tends
794# to duplicate a header already in the template file.
795#
796sub output_blockhead_rst(%) {
797 my %args = %{$_[0]};
798 my ($parameter, $section);
799
800 foreach $section (@{$args{'sectionlist'}}) {
801 next if (defined($nosymbol_table{$section}));
802
803 if ($output_selection != OUTPUT_INCLUDE) {
804 print "**$section**\n\n";
805 }
806 print_lineno($section_start_lines{$section});
807 output_highlight_rst($args{'sections'}{$section});
808 print "\n";
809 }
810}

--- 299 unchanged lines hidden (view full) ---

1110# generic output function for all types (function, struct/union, typedef, enum);
1111# calls the generated, variable output_ function name based on
1112# functype and output_mode
1113sub output_declaration {
1114 no strict 'refs';
1115 my $name = shift;
1116 my $functype = shift;
1117 my $func = "output_${functype}_$output_mode";
803 if ($output_selection != OUTPUT_INCLUDE) {
804 print "**$section**\n\n";
805 }
806 print_lineno($section_start_lines{$section});
807 output_highlight_rst($args{'sections'}{$section});
808 print "\n";
809 }
810}

--- 299 unchanged lines hidden (view full) ---

1110# generic output function for all types (function, struct/union, typedef, enum);
1111# calls the generated, variable output_ function name based on
1112# functype and output_mode
1113sub output_declaration {
1114 no strict 'refs';
1115 my $name = shift;
1116 my $functype = shift;
1117 my $func = "output_${functype}_$output_mode";
1118
1119 return if (defined($nosymbol_table{$name}));
1120
1118 if (($output_selection == OUTPUT_ALL) ||
1119 (($output_selection == OUTPUT_INCLUDE ||
1120 $output_selection == OUTPUT_EXPORTED) &&
1121 defined($function_table{$name})) ||
1121 if (($output_selection == OUTPUT_ALL) ||
1122 (($output_selection == OUTPUT_INCLUDE ||
1123 $output_selection == OUTPUT_EXPORTED) &&
1124 defined($function_table{$name})) ||
1122 (($output_selection == OUTPUT_EXCLUDE ||
1123 $output_selection == OUTPUT_INTERNAL) &&
1125 ($output_selection == OUTPUT_INTERNAL &&
1124 !($functype eq "function" && defined($function_table{$name}))))
1125 {
1126 &$func(@_);
1127 $section_counter++;
1128 }
1129}
1130
1131##

--- 164 unchanged lines hidden (view full) ---

1296 }
1297}
1298
1299
1300sub show_warnings($$) {
1301 my $functype = shift;
1302 my $name = shift;
1303
1126 !($functype eq "function" && defined($function_table{$name}))))
1127 {
1128 &$func(@_);
1129 $section_counter++;
1130 }
1131}
1132
1133##

--- 164 unchanged lines hidden (view full) ---

1298 }
1299}
1300
1301
1302sub show_warnings($$) {
1303 my $functype = shift;
1304 my $name = shift;
1305
1306 return 0 if (defined($nosymbol_table{$name}));
1307
1304 return 1 if ($output_selection == OUTPUT_ALL);
1305
1306 if ($output_selection == OUTPUT_EXPORTED) {
1307 if (defined($function_table{$name})) {
1308 return 1;
1309 } else {
1310 return 0;
1311 }

--- 7 unchanged lines hidden (view full) ---

1319 }
1320 if ($output_selection == OUTPUT_INCLUDE) {
1321 if (defined($function_table{$name})) {
1322 return 1;
1323 } else {
1324 return 0;
1325 }
1326 }
1308 return 1 if ($output_selection == OUTPUT_ALL);
1309
1310 if ($output_selection == OUTPUT_EXPORTED) {
1311 if (defined($function_table{$name})) {
1312 return 1;
1313 } else {
1314 return 0;
1315 }

--- 7 unchanged lines hidden (view full) ---

1323 }
1324 if ($output_selection == OUTPUT_INCLUDE) {
1325 if (defined($function_table{$name})) {
1326 return 1;
1327 } else {
1328 return 0;
1329 }
1330 }
1327 if ($output_selection == OUTPUT_EXCLUDE) {
1328 if (!defined($function_table{$name})) {
1329 return 1;
1330 } else {
1331 return 0;
1332 }
1333 }
1334 die("Please add the new output type at show_warnings()");
1335}
1336
1337sub dump_enum($$) {
1338 my $x = shift;
1339 my $file = shift;
1340 my $members;
1341

--- 605 unchanged lines hidden (view full) ---

1947 if (!open(IN,"<$file")) {
1948 print STDERR "Error: Cannot open file $file\n";
1949 ++$errors;
1950 return;
1951 }
1952
1953 while (<IN>) {
1954 if (/$export_symbol/) {
1331 die("Please add the new output type at show_warnings()");
1332}
1333
1334sub dump_enum($$) {
1335 my $x = shift;
1336 my $file = shift;
1337 my $members;
1338

--- 605 unchanged lines hidden (view full) ---

1944 if (!open(IN,"<$file")) {
1945 print STDERR "Error: Cannot open file $file\n";
1946 ++$errors;
1947 return;
1948 }
1949
1950 while (<IN>) {
1951 if (/$export_symbol/) {
1952 next if (defined($nosymbol_table{$2}));
1955 $function_table{$2} = 1;
1956 }
1957 }
1958
1959 close(IN);
1960}
1961
1962#

--- 408 unchanged lines hidden --- 		1953 $function_table{$2} = 1;
1954 }
1955 }
1956
1957 close(IN);
1958}
1959
1960#

--- 408 unchanged lines hidden ---