kernel-doc (837664528e17380cfacfb766de37df31572f07a0) kernel-doc (0d8c39e6c6dd97fc7fc40e93b44d76bb6dc4d4e4)
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

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

201my $type_struct = '\&((struct\s*)*[_\w]+)';
202my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
203my $type_env = '(\$\w+)';
204
205# Output conversion substitutions.
206# One for each output format
207
208# these work fairly well
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

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

201my $type_struct = '\&((struct\s*)*[_\w]+)';
202my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
203my $type_env = '(\$\w+)';
204
205# Output conversion substitutions.
206# One for each output format
207
208# these work fairly well
209my %highlights_html = ( $type_constant, "<i>\$1</i>",
210 $type_func, "<b>\$1</b>",
211 $type_struct_xml, "<i>\$1</i>",
212 $type_env, "<b><i>\$1</i></b>",
213 $type_param, "<tt><b>\$1</b></tt>" );
209my @highlights_html = (
210 [$type_constant, "<i>\$1</i>"],
211 [$type_func, "<b>\$1</b>"],
212 [$type_struct_xml, "<i>\$1</i>"],
213 [$type_env, "<b><i>\$1</i></b>"],
214 [$type_param, "<tt><b>\$1</b></tt>"]
215 );
214my $local_lt = "\\\\\\\\lt:";
215my $local_gt = "\\\\\\\\gt:";
216my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
217
218# html version 5
216my $local_lt = "\\\\\\\\lt:";
217my $local_gt = "\\\\\\\\gt:";
218my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
219
220# html version 5
219my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
220 $type_func, "<span class=\"func\">\$1</span>",
221 $type_struct_xml, "<span class=\"struct\">\$1</span>",
222 $type_env, "<span class=\"env\">\$1</span>",
223 $type_param, "<span class=\"param\">\$1</span>" );
221my @highlights_html5 = (
222 [$type_constant, "<span class=\"const\">\$1</span>"],
223 [$type_func, "<span class=\"func\">\$1</span>"],
224 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
225 [$type_env, "<span class=\"env\">\$1</span>"],
226 [$type_param, "<span class=\"param\">\$1</span>]"]
227 );
224my $blankline_html5 = $local_lt . "br /" . $local_gt;
225
226# XML, docbook format
228my $blankline_html5 = $local_lt . "br /" . $local_gt;
229
230# XML, docbook format
227my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
228 $type_constant, "<constant>\$1</constant>",
229 $type_func, "<function>\$1</function>",
230 $type_struct_xml, "<structname>\$1</structname>",
231 $type_env, "<envar>\$1</envar>",
232 $type_param, "<parameter>\$1</parameter>" );
231my @highlights_xml = (
232 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
233 [$type_constant, "<constant>\$1</constant>"],
234 [$type_struct_xml, "<structname>\$1</structname>"],
235 [$type_param, "<parameter>\$1</parameter>"],
236 [$type_func, "<function>\$1</function>"],
237 [$type_env, "<envar>\$1</envar>"]
238 );
233my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
234
235# gnome, docbook format
239my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
240
241# gnome, docbook format
236my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
237 $type_func, "<function>\$1</function>",
238 $type_struct, "<structname>\$1</structname>",
239 $type_env, "<envar>\$1</envar>",
240 $type_param, "<parameter>\$1</parameter>" );
242my @highlights_gnome = (
243 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
244 [$type_func, "<function>\$1</function>"],
245 [$type_struct, "<structname>\$1</structname>"],
246 [$type_env, "<envar>\$1</envar>"],
247 [$type_param, "<parameter>\$1</parameter>" ]
248 );
241my $blankline_gnome = "</para><para>\n";
242
243# these are pretty rough
249my $blankline_gnome = "</para><para>\n";
250
251# these are pretty rough
244my %highlights_man = ( $type_constant, "\$1",
245 $type_func, "\\\\fB\$1\\\\fP",
246 $type_struct, "\\\\fI\$1\\\\fP",
247 $type_param, "\\\\fI\$1\\\\fP" );
252my @highlights_man = (
253 [$type_constant, "\$1"],
254 [$type_func, "\\\\fB\$1\\\\fP"],
255 [$type_struct, "\\\\fI\$1\\\\fP"],
256 [$type_param, "\\\\fI\$1\\\\fP"]
257 );
248my $blankline_man = "";
249
250# text-mode
258my $blankline_man = "";
259
260# text-mode
251my %highlights_text = ( $type_constant, "\$1",
252 $type_func, "\$1",
253 $type_struct, "\$1",
254 $type_param, "\$1" );
261my @highlights_text = (
262 [$type_constant, "\$1"],
263 [$type_func, "\$1"],
264 [$type_struct, "\$1"],
265 [$type_param, "\$1"]
266 );
255my $blankline_text = "";
256
257# list mode
267my $blankline_text = "";
268
269# list mode
258my %highlights_list = ( $type_constant, "\$1",
259 $type_func, "\$1",
260 $type_struct, "\$1",
261 $type_param, "\$1" );
270my @highlights_list = (
271 [$type_constant, "\$1"],
272 [$type_func, "\$1"],
273 [$type_struct, "\$1"],
274 [$type_param, "\$1"]
275 );
262my $blankline_list = "";
263
264# read arguments
265if ($#ARGV == -1) {
266 usage();
267}
268
269my $kernelversion;
270my $dohighlight = "";
271
272my $verbose = 0;
273my $output_mode = "man";
274my $output_preformatted = 0;
275my $no_doc_sections = 0;
276my $blankline_list = "";
277
278# read arguments
279if ($#ARGV == -1) {
280 usage();
281}
282
283my $kernelversion;
284my $dohighlight = "";
285
286my $verbose = 0;
287my $output_mode = "man";
288my $output_preformatted = 0;
289my $no_doc_sections = 0;
276my %highlights = %highlights_man;
290my @highlights = @highlights_man;
277my $blankline = $blankline_man;
278my $modulename = "Kernel API";
279my $function_only = 0;
280my $show_not_found = 0;
281
282my @build_time;
283if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
284 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {

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

369my $undescribed = "-- undescribed --";
370
371reset_state();
372
373while ($ARGV[0] =~ m/^-(.*)/) {
374 my $cmd = shift @ARGV;
375 if ($cmd eq "-html") {
376 $output_mode = "html";
291my $blankline = $blankline_man;
292my $modulename = "Kernel API";
293my $function_only = 0;
294my $show_not_found = 0;
295
296my @build_time;
297if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
298 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {

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

383my $undescribed = "-- undescribed --";
384
385reset_state();
386
387while ($ARGV[0] =~ m/^-(.*)/) {
388 my $cmd = shift @ARGV;
389 if ($cmd eq "-html") {
390 $output_mode = "html";
377 %highlights = %highlights_html;
391 @highlights = @highlights_html;
378 $blankline = $blankline_html;
379 } elsif ($cmd eq "-html5") {
380 $output_mode = "html5";
392 $blankline = $blankline_html;
393 } elsif ($cmd eq "-html5") {
394 $output_mode = "html5";
381 %highlights = %highlights_html5;
395 @highlights = @highlights_html5;
382 $blankline = $blankline_html5;
383 } elsif ($cmd eq "-man") {
384 $output_mode = "man";
396 $blankline = $blankline_html5;
397 } elsif ($cmd eq "-man") {
398 $output_mode = "man";
385 %highlights = %highlights_man;
399 @highlights = @highlights_man;
386 $blankline = $blankline_man;
387 } elsif ($cmd eq "-text") {
388 $output_mode = "text";
400 $blankline = $blankline_man;
401 } elsif ($cmd eq "-text") {
402 $output_mode = "text";
389 %highlights = %highlights_text;
403 @highlights = @highlights_text;
390 $blankline = $blankline_text;
391 } elsif ($cmd eq "-docbook") {
392 $output_mode = "xml";
404 $blankline = $blankline_text;
405 } elsif ($cmd eq "-docbook") {
406 $output_mode = "xml";
393 %highlights = %highlights_xml;
407 @highlights = @highlights_xml;
394 $blankline = $blankline_xml;
395 } elsif ($cmd eq "-list") {
396 $output_mode = "list";
408 $blankline = $blankline_xml;
409 } elsif ($cmd eq "-list") {
410 $output_mode = "list";
397 %highlights = %highlights_list;
411 @highlights = @highlights_list;
398 $blankline = $blankline_list;
399 } elsif ($cmd eq "-gnome") {
400 $output_mode = "gnome";
412 $blankline = $blankline_list;
413 } elsif ($cmd eq "-gnome") {
414 $output_mode = "gnome";
401 %highlights = %highlights_gnome;
415 @highlights = @highlights_gnome;
402 $blankline = $blankline_gnome;
403 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
404 $modulename = shift @ARGV;
405 } elsif ($cmd eq "-function") { # to only output specific functions
406 $function_only = 1;
407 $function = shift @ARGV;
408 $function_table{$function} = 1;
409 } elsif ($cmd eq "-nofunction") { # to only output specific functions

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

1741# functype and output_mode
1742sub output_declaration {
1743 no strict 'refs';
1744 my $name = shift;
1745 my $functype = shift;
1746 my $func = "output_${functype}_$output_mode";
1747 if (($function_only==0) ||
1748 ( $function_only == 1 && defined($function_table{$name})) ||
416 $blankline = $blankline_gnome;
417 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
418 $modulename = shift @ARGV;
419 } elsif ($cmd eq "-function") { # to only output specific functions
420 $function_only = 1;
421 $function = shift @ARGV;
422 $function_table{$function} = 1;
423 } elsif ($cmd eq "-nofunction") { # to only output specific functions

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

1755# functype and output_mode
1756sub output_declaration {
1757 no strict 'refs';
1758 my $name = shift;
1759 my $functype = shift;
1760 my $func = "output_${functype}_$output_mode";
1761 if (($function_only==0) ||
1762 ( $function_only == 1 && defined($function_table{$name})) ||
1749 ( $function_only == 2 && !defined($function_table{$name})))
1763 ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
1750 {
1751 &$func(@_);
1752 $section_counter++;
1753 }
1754}
1755
1756##
1757# generic output function - calls the right one based on current output mode.

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

1786 $declaration_name = $2;
1787 my $members = $3;
1788
1789 # ignore embedded structs or unions
1790 $members =~ s/({.*})//g;
1791 $nested = $1;
1792
1793 # ignore members marked private:
1764 {
1765 &$func(@_);
1766 $section_counter++;
1767 }
1768}
1769
1770##
1771# generic output function - calls the right one based on current output mode.

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

1800 $declaration_name = $2;
1801 my $members = $3;
1802
1803 # ignore embedded structs or unions
1804 $members =~ s/({.*})//g;
1805 $nested = $1;
1806
1807 # ignore members marked private:
1794 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
1795 $members =~ s/\/\*\s*private:.*//gos;
1808 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1809 $members =~ s/\/\*\s*private:.*//gosi;
1796 # strip comments:
1797 $members =~ s/\/\*.*?\*\///gos;
1798 $nested =~ s/\/\*.*?\*\///gos;
1799 # strip kmemcheck_bitfield_{begin,end}.*;
1800 $members =~ s/kmemcheck_bitfield_.*?;//gos;
1801 # strip attributes
1802 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1803 $members =~ s/__aligned\s*\([^;]*\)//gos;

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

1864 }
1865}
1866
1867sub dump_typedef($$) {
1868 my $x = shift;
1869 my $file = shift;
1870
1871 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1810 # strip comments:
1811 $members =~ s/\/\*.*?\*\///gos;
1812 $nested =~ s/\/\*.*?\*\///gos;
1813 # strip kmemcheck_bitfield_{begin,end}.*;
1814 $members =~ s/kmemcheck_bitfield_.*?;//gos;
1815 # strip attributes
1816 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1817 $members =~ s/__aligned\s*\([^;]*\)//gos;

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

1878 }
1879}
1880
1881sub dump_typedef($$) {
1882 my $x = shift;
1883 my $file = shift;
1884
1885 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1872
1873 # Parse function prototypes
1874 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
1875 # Function typedefs
1876 $return_type = $1;
1877 $declaration_name = $2;
1878 my $args = $3;
1879
1880 create_parameterlist($args, ',', $file);
1881
1882 output_declaration($declaration_name,
1883 'function',
1884 {'function' => $declaration_name,
1885 'module' => $modulename,
1886 'functiontype' => $return_type,
1887 'parameterlist' => \@parameterlist,
1888 'parameterdescs' => \%parameterdescs,
1889 'parametertypes' => \%parametertypes,
1890 'sectionlist' => \@sectionlist,
1891 'sections' => \%sections,
1892 'purpose' => $declaration_purpose
1893 });
1894 return;
1895 }
1896
1897 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1898 $x =~ s/\(*.\)\s*;$/;/;
1899 $x =~ s/\[*.\]\s*;$/;/;
1900 }
1901
1902 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1903 $declaration_name = $1;
1904

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

2411
2412sub process_file($) {
2413 my $file;
2414 my $identifier;
2415 my $func;
2416 my $descr;
2417 my $in_purpose = 0;
2418 my $initial_section_counter = $section_counter;
1886 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1887 $x =~ s/\(*.\)\s*;$/;/;
1888 $x =~ s/\[*.\]\s*;$/;/;
1889 }
1890
1891 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1892 $declaration_name = $1;
1893

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

2400
2401sub process_file($) {
2402 my $file;
2403 my $identifier;
2404 my $func;
2405 my $descr;
2406 my $in_purpose = 0;
2407 my $initial_section_counter = $section_counter;
2408 my ($orig_file) = @_;
2419
2420 if (defined($ENV{'SRCTREE'})) {
2409
2410 if (defined($ENV{'SRCTREE'})) {
2421 $file = "$ENV{'SRCTREE'}" . "/" . "@_";
2411 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2422 }
2423 else {
2412 }
2413 else {
2424 $file = "@_";
2414 $file = $orig_file;
2425 }
2426 if (defined($source_map{$file})) {
2427 $file = $source_map{$file};
2428 }
2429
2430 if (!open(IN,"<$file")) {
2431 print STDERR "Error: Cannot open file $file\n";
2432 ++$errors;

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

2660 if (($function_only == 1) && ($show_not_found == 1)) {
2661 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2662 }
2663 if ($output_mode eq "xml") {
2664 # The template wants at least one RefEntry here; make one.
2665 print "<refentry>\n";
2666 print " <refnamediv>\n";
2667 print " <refname>\n";
2415 }
2416 if (defined($source_map{$file})) {
2417 $file = $source_map{$file};
2418 }
2419
2420 if (!open(IN,"<$file")) {
2421 print STDERR "Error: Cannot open file $file\n";
2422 ++$errors;

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

2650 if (($function_only == 1) && ($show_not_found == 1)) {
2651 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2652 }
2653 if ($output_mode eq "xml") {
2654 # The template wants at least one RefEntry here; make one.
2655 print "<refentry>\n";
2656 print " <refnamediv>\n";
2657 print " <refname>\n";
2668 print " ${file}\n";
2658 print " ${orig_file}\n";
2669 print " </refname>\n";
2670 print " <refpurpose>\n";
2671 print " Document generation inconsistency\n";
2672 print " </refpurpose>\n";
2673 print " </refnamediv>\n";
2674 print " <refsect1>\n";
2675 print " <title>\n";
2676 print " Oops\n";
2677 print " </title>\n";
2678 print " <warning>\n";
2679 print " <para>\n";
2680 print " The template for this document tried to insert\n";
2681 print " the structured comment from the file\n";
2659 print " </refname>\n";
2660 print " <refpurpose>\n";
2661 print " Document generation inconsistency\n";
2662 print " </refpurpose>\n";
2663 print " </refnamediv>\n";
2664 print " <refsect1>\n";
2665 print " <title>\n";
2666 print " Oops\n";
2667 print " </title>\n";
2668 print " <warning>\n";
2669 print " <para>\n";
2670 print " The template for this document tried to insert\n";
2671 print " the structured comment from the file\n";
2682 print " <filename>${file}</filename> at this point,\n";
2672 print " <filename>${orig_file}</filename> at this point,\n";
2683 print " but none was found.\n";
2684 print " This dummy section is inserted to allow\n";
2685 print " generation to continue.\n";
2686 print " </para>\n";
2687 print " </warning>\n";
2688 print " </refsect1>\n";
2689 print "</refentry>\n";
2690 }
2691 }
2692}
2693
2694
2695$kernelversion = get_kernel_version();
2696
2697# generate a sequence of code that will splice in highlighting information
2698# using the s// operator.
2673 print " but none was found.\n";
2674 print " This dummy section is inserted to allow\n";
2675 print " generation to continue.\n";
2676 print " </para>\n";
2677 print " </warning>\n";
2678 print " </refsect1>\n";
2679 print "</refentry>\n";
2680 }
2681 }
2682}
2683
2684
2685$kernelversion = get_kernel_version();
2686
2687# generate a sequence of code that will splice in highlighting information
2688# using the s// operator.
2699foreach my $pattern (sort keys %highlights) {
2700# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
2701 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
2689foreach my $k (keys @highlights) {
2690 my $pattern = $highlights[$k][0];
2691 my $result = $highlights[$k][1];
2692# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2693 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
2702}
2703
2704# Read the file that maps relative names to absolute names for
2705# separate source and object directories and for shadow trees.
2706if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2707 my ($relname, $absname);
2708 while(<SOURCE_MAP>) {
2709 chop();

--- 19 unchanged lines hidden --- 		2694}
2695
2696# Read the file that maps relative names to absolute names for
2697# separate source and object directories and for shadow trees.
2698if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2699 my ($relname, $absname);
2700 while(<SOURCE_MAP>) {
2701 chop();

--- 19 unchanged lines hidden ---