kernel-doc (1b9bc22d71c75d4145688428c92c5123bd8697e3) kernel-doc (b112e0f73fe8e9e69e60bc9d6d16217795259c3c)
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-2007 Randy Dunlap ##

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

49# kernel-doc [ -docbook | -html | -text | -man ]
50# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
51# or
52# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
53#
54# Set output format using one of -docbook -html -text or -man. Default is man.
55#
56# -function funcname
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-2007 Randy Dunlap ##

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

49# kernel-doc [ -docbook | -html | -text | -man ]
50# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
51# or
52# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
53#
54# Set output format using one of -docbook -html -text or -man. Default is man.
55#
56# -function funcname
57# If set, then only generate documentation for the given function(s). All
58# other functions are ignored.
57# If set, then only generate documentation for the given function(s) or
58# DOC: section titles. All other functions and DOC: sections are ignored.
59#
60# -nofunction funcname
59#
60# -nofunction funcname
61# If set, then only generate documentation for the other function(s).
62# Cannot be used together with -function
63# (yes, that's a bug -- perl hackers can fix it 8))
61# If set, then only generate documentation for the other function(s)/DOC:
62# sections. Cannot be used together with -function (yes, that's a bug --
63# perl hackers can fix it 8))
64#
65# c files - list of 'c' files to process
66#
67# All output goes to stdout, with errors to stderr.
68
69#
70# format of comments.
71# In the following table, (...)? signifies optional structure.

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

369 } else {
370# print STDERR "other section '$name' = '$contents'\n";
371 $sections{$name} = $contents;
372 push @sectionlist, $name;
373 }
374}
375
376##
64#
65# c files - list of 'c' files to process
66#
67# All output goes to stdout, with errors to stderr.
68
69#
70# format of comments.
71# In the following table, (...)? signifies optional structure.

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

369 } else {
370# print STDERR "other section '$name' = '$contents'\n";
371 $sections{$name} = $contents;
372 push @sectionlist, $name;
373 }
374}
375
376##
377# dump DOC: section after checking that it should go out
378#
379sub dump_doc_section {
380 my $name = shift;
381 my $contents = join "\n", @_;
382
383 if (($function_only == 0) ||
384 ( $function_only == 1 && defined($function_table{$name})) ||
385 ( $function_only == 2 && !defined($function_table{$name})))
386 {
387 dump_section $name, $contents;
388 output_blockhead({'sectionlist' => \@sectionlist,
389 'sections' => \%sections,
390 'module' => $modulename,
391 'content-only' => ($function_only != 0), });
392 }
393}
394
395##
377# output function
378#
379# parameterdescs, a hash.
380# function => "function name"
381# parameterlist => @list of parameters
382# parameterdescs => %parameter descriptions
383# sectionlist => @list of sections
384# sections => %section descriptions

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

559 print "<dd>";
560 output_highlight($args{'parameterdescs'}{$parameter_name});
561 }
562 print "</dl>\n";
563 output_section_html(@_);
564 print "<hr>\n";
565}
566
396# output function
397#
398# parameterdescs, a hash.
399# function => "function name"
400# parameterlist => @list of parameters
401# parameterdescs => %parameter descriptions
402# sectionlist => @list of sections
403# sections => %section descriptions

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

578 print "<dd>";
579 output_highlight($args{'parameterdescs'}{$parameter_name});
580 }
581 print "</dl>\n";
582 output_section_html(@_);
583 print "<hr>\n";
584}
585
567# output intro in html
568sub output_intro_html(%) {
586# output DOC: block header in html
587sub output_blockhead_html(%) {
569 my %args = %{$_[0]};
570 my ($parameter, $section);
571 my $count;
572
573 foreach $section (@{$args{'sectionlist'}}) {
574 print "<h3>$section</h3>\n";
575 print "<ul>\n";
576 output_highlight($args{'sections'}{$section});

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

866 print "</refsynopsisdiv>\n";
867
868 output_section_xml(@_);
869
870 print "</refentry>\n\n";
871}
872
873# output in XML DocBook
588 my %args = %{$_[0]};
589 my ($parameter, $section);
590 my $count;
591
592 foreach $section (@{$args{'sectionlist'}}) {
593 print "<h3>$section</h3>\n";
594 print "<ul>\n";
595 output_highlight($args{'sections'}{$section});

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

885 print "</refsynopsisdiv>\n";
886
887 output_section_xml(@_);
888
889 print "</refentry>\n\n";
890}
891
892# output in XML DocBook
874sub output_intro_xml(%) {
893sub output_blockhead_xml(%) {
875 my %args = %{$_[0]};
876 my ($parameter, $section);
877 my $count;
878
879 my $id = $args{'module'};
880 $id =~ s/[^A-Za-z0-9]/-/g;
881
882 # print out each section
883 $lineprefix=" ";
884 foreach $section (@{$args{'sectionlist'}}) {
894 my %args = %{$_[0]};
895 my ($parameter, $section);
896 my $count;
897
898 my $id = $args{'module'};
899 $id =~ s/[^A-Za-z0-9]/-/g;
900
901 # print out each section
902 $lineprefix=" ";
903 foreach $section (@{$args{'sectionlist'}}) {
885 print "<refsect1>\n <title>$section</title>\n <para>\n";
904 if (!$args{'content-only'}) {
905 print "<refsect1>\n <title>$section</title>\n";
906 }
886 if ($section =~ m/EXAMPLE/i) {
887 print "<example><para>\n";
907 if ($section =~ m/EXAMPLE/i) {
908 print "<example><para>\n";
909 } else {
910 print "<para>\n";
888 }
889 output_highlight($args{'sections'}{$section});
890 if ($section =~ m/EXAMPLE/i) {
891 print "</para></example>\n";
911 }
912 output_highlight($args{'sections'}{$section});
913 if ($section =~ m/EXAMPLE/i) {
914 print "</para></example>\n";
915 } else {
916 print "</para>";
892 }
917 }
893 print " </para>\n</refsect1>\n";
918 if (!$args{'content-only'}) {
919 print "\n</refsect1>\n";
920 }
894 }
895
896 print "\n\n";
897}
898
899# output in XML DocBook
900sub output_function_gnome {
901 my %args = %{$_[0]};

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

1132 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1133
1134 foreach $section (@{$args{'sectionlist'}}) {
1135 print ".SH \"$section\"\n";
1136 output_highlight($args{'sections'}{$section});
1137 }
1138}
1139
921 }
922
923 print "\n\n";
924}
925
926# output in XML DocBook
927sub output_function_gnome {
928 my %args = %{$_[0]};

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

1159 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1160
1161 foreach $section (@{$args{'sectionlist'}}) {
1162 print ".SH \"$section\"\n";
1163 output_highlight($args{'sections'}{$section});
1164 }
1165}
1166
1140sub output_intro_man(%) {
1167sub output_blockhead_man(%) {
1141 my %args = %{$_[0]};
1142 my ($parameter, $section);
1143 my $count;
1144
1145 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1146
1147 foreach $section (@{$args{'sectionlist'}}) {
1148 print ".SH \"$section\"\n";

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

1289 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1290 print "$parameter\n\t";
1291 print $args{'parameterdescs'}{$parameter_name}."\n";
1292 }
1293 print "\n";
1294 output_section_text(@_);
1295}
1296
1168 my %args = %{$_[0]};
1169 my ($parameter, $section);
1170 my $count;
1171
1172 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1173
1174 foreach $section (@{$args{'sectionlist'}}) {
1175 print ".SH \"$section\"\n";

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

1316 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1317 print "$parameter\n\t";
1318 print $args{'parameterdescs'}{$parameter_name}."\n";
1319 }
1320 print "\n";
1321 output_section_text(@_);
1322}
1323
1297sub output_intro_text(%) {
1324sub output_blockhead_text(%) {
1298 my %args = %{$_[0]};
1299 my ($parameter, $section);
1300
1301 foreach $section (@{$args{'sectionlist'}}) {
1302 print " $section:\n";
1303 print " -> ";
1304 output_highlight($args{'sections'}{$section});
1305 }

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

1320 {
1321 &$func(@_);
1322 $section_counter++;
1323 }
1324}
1325
1326##
1327# generic output function - calls the right one based on current output mode.
1325 my %args = %{$_[0]};
1326 my ($parameter, $section);
1327
1328 foreach $section (@{$args{'sectionlist'}}) {
1329 print " $section:\n";
1330 print " -> ";
1331 output_highlight($args{'sections'}{$section});
1332 }

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

1347 {
1348 &$func(@_);
1349 $section_counter++;
1350 }
1351}
1352
1353##
1354# generic output function - calls the right one based on current output mode.
1328sub output_intro {
1355sub output_blockhead {
1329 no strict 'refs';
1356 no strict 'refs';
1330 my $func = "output_intro_".$output_mode;
1357 my $func = "output_blockhead_".$output_mode;
1331 &$func(@_);
1332 $section_counter++;
1333}
1334
1335##
1336# takes a declaration (struct, union, enum, typedef) and
1337# invokes the right handler. NOT called for functions.
1338sub dump_declaration($$) {

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

1921 if ($decl_type eq 'function') {
1922 process_state3_function($_, $file);
1923 } else {
1924 process_state3_type($_, $file);
1925 }
1926 } elsif ($state == 4) {
1927 # Documentation block
1928 if (/$doc_block/) {
1358 &$func(@_);
1359 $section_counter++;
1360}
1361
1362##
1363# takes a declaration (struct, union, enum, typedef) and
1364# invokes the right handler. NOT called for functions.
1365sub dump_declaration($$) {

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

1948 if ($decl_type eq 'function') {
1949 process_state3_function($_, $file);
1950 } else {
1951 process_state3_type($_, $file);
1952 }
1953 } elsif ($state == 4) {
1954 # Documentation block
1955 if (/$doc_block/) {
1929 dump_section($section, xml_escape($contents));
1930 output_intro({'sectionlist' => \@sectionlist,
1931 'sections' => \%sections });
1956 dump_doc_section($section, xml_escape($contents));
1932 $contents = "";
1933 $function = "";
1934 %constants = ();
1935 %parameterdescs = ();
1936 %parametertypes = ();
1937 @parameterlist = ();
1938 %sections = ();
1939 @sectionlist = ();
1940 $prototype = "";
1941 if ( $1 eq "" ) {
1942 $section = $section_intro;
1943 } else {
1944 $section = $1;
1945 }
1946 }
1947 elsif (/$doc_end/)
1948 {
1957 $contents = "";
1958 $function = "";
1959 %constants = ();
1960 %parameterdescs = ();
1961 %parametertypes = ();
1962 @parameterlist = ();
1963 %sections = ();
1964 @sectionlist = ();
1965 $prototype = "";
1966 if ( $1 eq "" ) {
1967 $section = $section_intro;
1968 } else {
1969 $section = $1;
1970 }
1971 }
1972 elsif (/$doc_end/)
1973 {
1949 dump_section($section, xml_escape($contents));
1950 output_intro({'sectionlist' => \@sectionlist,
1951 'sections' => \%sections });
1974 dump_doc_section($section, xml_escape($contents));
1952 $contents = "";
1953 $function = "";
1954 %constants = ();
1955 %parameterdescs = ();
1956 %parametertypes = ();
1957 @parameterlist = ();
1958 %sections = ();
1959 @sectionlist = ();

--- 48 unchanged lines hidden --- 		1975 $contents = "";
1976 $function = "";
1977 %constants = ();
1978 %parameterdescs = ();
1979 %parametertypes = ();
1980 @parameterlist = ();
1981 %sections = ();
1982 @sectionlist = ();

--- 48 unchanged lines hidden ---