diff options
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-x | scripts/kernel-doc | 68 |
1 files changed, 34 insertions, 34 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 940fe348009f..99fe4b7fb2f1 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc | |||
@@ -90,28 +90,28 @@ use strict; | |||
90 | # * my_function - does my stuff | 90 | # * my_function - does my stuff |
91 | # * @my_arg: its mine damnit | 91 | # * @my_arg: its mine damnit |
92 | # * | 92 | # * |
93 | # * Does my stuff explained. | 93 | # * Does my stuff explained. |
94 | # */ | 94 | # */ |
95 | # | 95 | # |
96 | # or, could also use: | 96 | # or, could also use: |
97 | # /** | 97 | # /** |
98 | # * my_function - does my stuff | 98 | # * my_function - does my stuff |
99 | # * @my_arg: its mine damnit | 99 | # * @my_arg: its mine damnit |
100 | # * Description: Does my stuff explained. | 100 | # * Description: Does my stuff explained. |
101 | # */ | 101 | # */ |
102 | # etc. | 102 | # etc. |
103 | # | 103 | # |
104 | # Beside functions you can also write documentation for structs, unions, | 104 | # Beside functions you can also write documentation for structs, unions, |
105 | # enums and typedefs. Instead of the function name you must write the name | 105 | # enums and typedefs. Instead of the function name you must write the name |
106 | # of the declaration; the struct/union/enum/typedef must always precede | 106 | # of the declaration; the struct/union/enum/typedef must always precede |
107 | # the name. Nesting of declarations is not supported. | 107 | # the name. Nesting of declarations is not supported. |
108 | # Use the argument mechanism to document members or constants. | 108 | # Use the argument mechanism to document members or constants. |
109 | # e.g. | 109 | # e.g. |
110 | # /** | 110 | # /** |
111 | # * struct my_struct - short description | 111 | # * struct my_struct - short description |
112 | # * @a: first member | 112 | # * @a: first member |
113 | # * @b: second member | 113 | # * @b: second member |
114 | # * | 114 | # * |
115 | # * Longer description | 115 | # * Longer description |
116 | # */ | 116 | # */ |
117 | # struct my_struct { | 117 | # struct my_struct { |
@@ -122,12 +122,12 @@ use strict; | |||
122 | # }; | 122 | # }; |
123 | # | 123 | # |
124 | # All descriptions can be multiline, except the short function description. | 124 | # All descriptions can be multiline, except the short function description. |
125 | # | 125 | # |
126 | # You can also add additional sections. When documenting kernel functions you | 126 | # You can also add additional sections. When documenting kernel functions you |
127 | # should document the "Context:" of the function, e.g. whether the functions | 127 | # should document the "Context:" of the function, e.g. whether the functions |
128 | # can be called form interrupts. Unlike other sections you can end it with an | 128 | # can be called form interrupts. Unlike other sections you can end it with an |
129 | # empty line. | 129 | # empty line. |
130 | # Example-sections should contain the string EXAMPLE so that they are marked | 130 | # Example-sections should contain the string EXAMPLE so that they are marked |
131 | # appropriately in DocBook. | 131 | # appropriately in DocBook. |
132 | # | 132 | # |
133 | # Example: | 133 | # Example: |
@@ -135,7 +135,7 @@ use strict; | |||
135 | # * user_function - function that can only be called in user context | 135 | # * user_function - function that can only be called in user context |
136 | # * @a: some argument | 136 | # * @a: some argument |
137 | # * Context: !in_interrupt() | 137 | # * Context: !in_interrupt() |
138 | # * | 138 | # * |
139 | # * Some description | 139 | # * Some description |
140 | # * Example: | 140 | # * Example: |
141 | # * user_function(22); | 141 | # * user_function(22); |
@@ -223,9 +223,9 @@ my %highlights = %highlights_man; | |||
223 | my $blankline = $blankline_man; | 223 | my $blankline = $blankline_man; |
224 | my $modulename = "Kernel API"; | 224 | my $modulename = "Kernel API"; |
225 | my $function_only = 0; | 225 | my $function_only = 0; |
226 | my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', | 226 | my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', |
227 | 'July', 'August', 'September', 'October', | 227 | 'July', 'August', 'September', 'October', |
228 | 'November', 'December')[(localtime)[4]] . | 228 | 'November', 'December')[(localtime)[4]] . |
229 | " " . ((localtime)[5]+1900); | 229 | " " . ((localtime)[5]+1900); |
230 | 230 | ||
231 | # Essentially these are globals | 231 | # Essentially these are globals |
@@ -236,7 +236,7 @@ my ($function, %function_table,%parametertypes,$declaration_purpose); | |||
236 | my ($type,$declaration_name,$return_type); | 236 | my ($type,$declaration_name,$return_type); |
237 | my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); | 237 | my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); |
238 | 238 | ||
239 | # Generated docbook code is inserted in a template at a point where | 239 | # Generated docbook code is inserted in a template at a point where |
240 | # docbook v3.1 requires a non-zero sequence of RefEntry's; see: | 240 | # docbook v3.1 requires a non-zero sequence of RefEntry's; see: |
241 | # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html | 241 | # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html |
242 | # We keep track of number of generated entries and generate a dummy | 242 | # We keep track of number of generated entries and generate a dummy |
@@ -365,7 +365,7 @@ sub dump_section { | |||
365 | # parameterdescs => %parameter descriptions | 365 | # parameterdescs => %parameter descriptions |
366 | # sectionlist => @list of sections | 366 | # sectionlist => @list of sections |
367 | # sections => %descriont descriptions | 367 | # sections => %descriont descriptions |
368 | # | 368 | # |
369 | 369 | ||
370 | sub output_highlight { | 370 | sub output_highlight { |
371 | my $contents = join "\n",@_; | 371 | my $contents = join "\n",@_; |
@@ -400,7 +400,7 @@ sub output_section_html(%) { | |||
400 | print "<blockquote>\n"; | 400 | print "<blockquote>\n"; |
401 | output_highlight($args{'sections'}{$section}); | 401 | output_highlight($args{'sections'}{$section}); |
402 | print "</blockquote>\n"; | 402 | print "</blockquote>\n"; |
403 | } | 403 | } |
404 | } | 404 | } |
405 | 405 | ||
406 | # output enum in html | 406 | # output enum in html |
@@ -551,7 +551,7 @@ sub output_intro_html(%) { | |||
551 | 551 | ||
552 | sub output_section_xml(%) { | 552 | sub output_section_xml(%) { |
553 | my %args = %{$_[0]}; | 553 | my %args = %{$_[0]}; |
554 | my $section; | 554 | my $section; |
555 | # print out each section | 555 | # print out each section |
556 | $lineprefix=" "; | 556 | $lineprefix=" "; |
557 | foreach $section (@{$args{'sectionlist'}}) { | 557 | foreach $section (@{$args{'sectionlist'}}) { |
@@ -778,7 +778,7 @@ sub output_enum_xml(%) { | |||
778 | print "</refsynopsisdiv>\n"; | 778 | print "</refsynopsisdiv>\n"; |
779 | 779 | ||
780 | print "<refsect1>\n"; | 780 | print "<refsect1>\n"; |
781 | print " <title>Constants</title>\n"; | 781 | print " <title>Constants</title>\n"; |
782 | print " <variablelist>\n"; | 782 | print " <variablelist>\n"; |
783 | foreach $parameter (@{$args{'parameterlist'}}) { | 783 | foreach $parameter (@{$args{'parameterlist'}}) { |
784 | my $parameter_name = $parameter; | 784 | my $parameter_name = $parameter; |
@@ -1157,7 +1157,7 @@ sub output_section_text(%) { | |||
1157 | foreach $section (@{$args{'sectionlist'}}) { | 1157 | foreach $section (@{$args{'sectionlist'}}) { |
1158 | print "$section:\n\n"; | 1158 | print "$section:\n\n"; |
1159 | output_highlight($args{'sections'}{$section}); | 1159 | output_highlight($args{'sections'}{$section}); |
1160 | } | 1160 | } |
1161 | print "\n\n"; | 1161 | print "\n\n"; |
1162 | } | 1162 | } |
1163 | 1163 | ||
@@ -1262,8 +1262,8 @@ sub output_declaration { | |||
1262 | my $name = shift; | 1262 | my $name = shift; |
1263 | my $functype = shift; | 1263 | my $functype = shift; |
1264 | my $func = "output_${functype}_$output_mode"; | 1264 | my $func = "output_${functype}_$output_mode"; |
1265 | if (($function_only==0) || | 1265 | if (($function_only==0) || |
1266 | ( $function_only == 1 && defined($function_table{$name})) || | 1266 | ( $function_only == 1 && defined($function_table{$name})) || |
1267 | ( $function_only == 2 && !defined($function_table{$name}))) | 1267 | ( $function_only == 2 && !defined($function_table{$name}))) |
1268 | { | 1268 | { |
1269 | &$func(@_); | 1269 | &$func(@_); |
@@ -1282,7 +1282,7 @@ sub output_intro { | |||
1282 | } | 1282 | } |
1283 | 1283 | ||
1284 | ## | 1284 | ## |
1285 | # takes a declaration (struct, union, enum, typedef) and | 1285 | # takes a declaration (struct, union, enum, typedef) and |
1286 | # invokes the right handler. NOT called for functions. | 1286 | # invokes the right handler. NOT called for functions. |
1287 | sub dump_declaration($$) { | 1287 | sub dump_declaration($$) { |
1288 | no strict 'refs'; | 1288 | no strict 'refs'; |
@@ -1352,7 +1352,7 @@ sub dump_enum($$) { | |||
1352 | } | 1352 | } |
1353 | 1353 | ||
1354 | } | 1354 | } |
1355 | 1355 | ||
1356 | output_declaration($declaration_name, | 1356 | output_declaration($declaration_name, |
1357 | 'enum', | 1357 | 'enum', |
1358 | {'enum' => $declaration_name, | 1358 | {'enum' => $declaration_name, |
@@ -1409,7 +1409,7 @@ sub create_parameterlist($$$) { | |||
1409 | while ($args =~ /(\([^\),]+),/) { | 1409 | while ($args =~ /(\([^\),]+),/) { |
1410 | $args =~ s/(\([^\),]+),/$1#/g; | 1410 | $args =~ s/(\([^\),]+),/$1#/g; |
1411 | } | 1411 | } |
1412 | 1412 | ||
1413 | foreach my $arg (split($splitter, $args)) { | 1413 | foreach my $arg (split($splitter, $args)) { |
1414 | # strip comments | 1414 | # strip comments |
1415 | $arg =~ s/\/\*.*\*\///; | 1415 | $arg =~ s/\/\*.*\*\///; |
@@ -1558,7 +1558,7 @@ sub dump_function($$) { | |||
1558 | return; | 1558 | return; |
1559 | } | 1559 | } |
1560 | 1560 | ||
1561 | output_declaration($declaration_name, | 1561 | output_declaration($declaration_name, |
1562 | 'function', | 1562 | 'function', |
1563 | {'function' => $declaration_name, | 1563 | {'function' => $declaration_name, |
1564 | 'module' => $modulename, | 1564 | 'module' => $modulename, |
@@ -1617,11 +1617,11 @@ sub reset_state { | |||
1617 | %sections = (); | 1617 | %sections = (); |
1618 | @sectionlist = (); | 1618 | @sectionlist = (); |
1619 | $prototype = ""; | 1619 | $prototype = ""; |
1620 | 1620 | ||
1621 | $state = 0; | 1621 | $state = 0; |
1622 | } | 1622 | } |
1623 | 1623 | ||
1624 | sub process_state3_function($$) { | 1624 | sub process_state3_function($$) { |
1625 | my $x = shift; | 1625 | my $x = shift; |
1626 | my $file = shift; | 1626 | my $file = shift; |
1627 | 1627 | ||
@@ -1640,7 +1640,7 @@ sub process_state3_function($$) { | |||
1640 | } | 1640 | } |
1641 | } | 1641 | } |
1642 | 1642 | ||
1643 | sub process_state3_type($$) { | 1643 | sub process_state3_type($$) { |
1644 | my $x = shift; | 1644 | my $x = shift; |
1645 | my $file = shift; | 1645 | my $file = shift; |
1646 | 1646 | ||
@@ -1780,7 +1780,7 @@ sub process_file($) { | |||
1780 | } elsif (/$doc_content/) { | 1780 | } elsif (/$doc_content/) { |
1781 | # miguel-style comment kludge, look for blank lines after | 1781 | # miguel-style comment kludge, look for blank lines after |
1782 | # @parameter line to signify start of description | 1782 | # @parameter line to signify start of description |
1783 | if ($1 eq "" && | 1783 | if ($1 eq "" && |
1784 | ($section =~ m/^@/ || $section eq $section_context)) { | 1784 | ($section =~ m/^@/ || $section eq $section_context)) { |
1785 | dump_section($section, xml_escape($contents)); | 1785 | dump_section($section, xml_escape($contents)); |
1786 | $section = $section_default; | 1786 | $section = $section_default; |
@@ -1790,7 +1790,7 @@ sub process_file($) { | |||
1790 | } | 1790 | } |
1791 | } else { | 1791 | } else { |
1792 | # i dont know - bad line? ignore. | 1792 | # i dont know - bad line? ignore. |
1793 | print STDERR "Warning(${file}:$.): bad line: $_"; | 1793 | print STDERR "Warning(${file}:$.): bad line: $_"; |
1794 | ++$warnings; | 1794 | ++$warnings; |
1795 | } | 1795 | } |
1796 | } elsif ($state == 3) { # scanning for function { (end of prototype) | 1796 | } elsif ($state == 3) { # scanning for function { (end of prototype) |
@@ -1845,7 +1845,7 @@ sub process_file($) { | |||
1845 | else | 1845 | else |
1846 | { | 1846 | { |
1847 | $contents .= $1 . "\n"; | 1847 | $contents .= $1 . "\n"; |
1848 | } | 1848 | } |
1849 | } | 1849 | } |
1850 | } | 1850 | } |
1851 | } | 1851 | } |