1 #!/usr/bin/env perl !! 1 #!/usr/bin/perl -w
2 # SPDX-License-Identifier: GPL-2.0 <<
3 # vim: softtabstop=4 <<
4 2
5 use warnings; <<
6 use strict; 3 use strict;
7 4
8 ## Copyright (c) 1998 Michael Zucchi, All Righ 5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
9 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@red 6 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
10 ## Copyright (C) 2001 Simon Huggins 7 ## Copyright (C) 2001 Simon Huggins ##
11 ## Copyright (C) 2005-2012 Randy Dunlap <<
12 ## Copyright (C) 2012 Dan Luedtke <<
13 ## 8 ## ##
14 ## #define enhancements by Armin Kuster <akuste 9 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
15 ## Copyright (c) 2000 MontaVista Software, Inc 10 ## Copyright (c) 2000 MontaVista Software, Inc. ##
16 # !! 11 ## ##
17 # Copyright (C) 2022 Tomasz Warniełło (POD) !! 12 ## This software falls under the GNU General Public License. ##
18 !! 13 ## Please read the COPYING file for more information ##
19 use Pod::Usage qw/pod2usage/; <<
20 <<
21 =head1 NAME <<
22 <<
23 kernel-doc - Print formatted kernel documentat <<
24 <<
25 =head1 SYNOPSIS <<
26 <<
27 kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wret <<
28 [ -man | <<
29 -rst [-sphinx-version VERSION] [-enable-l <<
30 -none <<
31 ] <<
32 [ <<
33 -export | <<
34 -internal | <<
35 [-function NAME] ... | <<
36 [-nosymbol NAME] ... <<
37 ] <<
38 [-no-doc-sections] <<
39 [-export-file FILE] ... <<
40 FILE ... <<
41 <<
42 Run `kernel-doc -h` for details. <<
43 <<
44 =head1 DESCRIPTION <<
45 <<
46 Read C language source or header FILEs, extrac <<
47 and print formatted documentation to standard <<
48 <<
49 The documentation comments are identified by t <<
50 <<
51 See Documentation/doc-guide/kernel-doc.rst for <<
52 <<
53 =cut <<
54 14
55 # more perldoc at the end of the file !! 15 # w.o. 03-11-2000: added the '-filelist' option.
56 16
57 ## init lots of data !! 17 # 18/01/2001 - Cleanups
>> 18 # Functions prototyped as foo(void) same as foo()
>> 19 # Stop eval'ing where we don't need to.
>> 20 # -- huggie@earth.li
>> 21
>> 22 # 27/06/2001 - Allowed whitespace after initial "/**" and
>> 23 # allowed comments before function declarations.
>> 24 # -- Christian Kreibich <ck@whoop.org>
>> 25
>> 26 # Still to do:
>> 27 # - add perldoc documentation
>> 28 # - Look more closely at some of the scarier bits :)
>> 29
>> 30 # 26/05/2001 - Support for separate source and object trees.
>> 31 # Return error code.
>> 32 # Keith Owens <kaos@ocs.com.au>
>> 33
>> 34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
>> 35 # Support for Context section; can be terminated using empty line
>> 36 # Small fixes (like spaces vs. \s in regex)
>> 37 # -- Tim Jansen <tim@tjansen.de>
>> 38
>> 39
>> 40 #
>> 41 # This will read a 'c' file and scan for embedded comments in the
>> 42 # style of gnome comments (+minor extensions - see below).
>> 43 #
>> 44
>> 45 # Note: This only supports 'c'.
>> 46
>> 47 # usage:
>> 48 # kerneldoc [ -docbook | -html | -text | -man ]
>> 49 # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
>> 50 # or
>> 51 # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
>> 52 #
>> 53 # Set output format using one of -docbook -html -text or -man. Default is man.
>> 54 #
>> 55 # -function funcname
>> 56 # If set, then only generate documentation for the given function(s). All
>> 57 # other functions are ignored.
>> 58 #
>> 59 # -nofunction funcname
>> 60 # If set, then only generate documentation for the other function(s). All
>> 61 # other functions are ignored. Cannot be used with -function together
>> 62 # (yes thats a bug - perl hackers can fix it 8))
>> 63 #
>> 64 # c files - list of 'c' files to process
>> 65 #
>> 66 # All output goes to stdout, with errors to stderr.
>> 67
>> 68 #
>> 69 # format of comments.
>> 70 # In the following table, (...)? signifies optional structure.
>> 71 # (...)* signifies 0 or more structure elements
>> 72 # /**
>> 73 # * function_name(:)? (- short description)?
>> 74 # (* @parameterx: (description of parameter x)?)*
>> 75 # (* a blank line)?
>> 76 # * (Description:)? (Description of function)?
>> 77 # * (section header: (section description)? )*
>> 78 # (*)?*/
>> 79 #
>> 80 # So .. the trivial example would be:
>> 81 #
>> 82 # /**
>> 83 # * my_function
>> 84 # **/
>> 85 #
>> 86 # If the Description: header tag is ommitted, then there must be a blank line
>> 87 # after the last parameter specification.
>> 88 # e.g.
>> 89 # /**
>> 90 # * my_function - does my stuff
>> 91 # * @my_arg: its mine damnit
>> 92 # *
>> 93 # * Does my stuff explained.
>> 94 # */
>> 95 #
>> 96 # or, could also use:
>> 97 # /**
>> 98 # * my_function - does my stuff
>> 99 # * @my_arg: its mine damnit
>> 100 # * Description: Does my stuff explained.
>> 101 # */
>> 102 # etc.
>> 103 #
>> 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
>> 106 # of the declaration; the struct/union/enum/typedef must always precede
>> 107 # the name. Nesting of declarations is not supported.
>> 108 # Use the argument mechanism to document members or constants. In
>> 109 # structs and unions you must declare one member per declaration
>> 110 # (comma-separated members are not allowed - the parser does not support
>> 111 # this).
>> 112 # e.g.
>> 113 # /**
>> 114 # * struct my_struct - short description
>> 115 # * @a: first member
>> 116 # * @b: second member
>> 117 # *
>> 118 # * Longer description
>> 119 # */
>> 120 # struct my_struct {
>> 121 # int a;
>> 122 # int b;
>> 123 # };
>> 124 #
>> 125 # All descriptions can be multiline, except the short function description.
>> 126 #
>> 127 # You can also add additional sections. When documenting kernel functions you
>> 128 # should document the "Context:" of the function, e.g. whether the functions
>> 129 # can be called form interrupts. Unlike other sections you can end it with an
>> 130 # empty line.
>> 131 # Example-sections should contain the string EXAMPLE so that they are marked
>> 132 # appropriately in DocBook.
>> 133 #
>> 134 # Example:
>> 135 # /**
>> 136 # * user_function - function that can only be called in user context
>> 137 # * @a: some argument
>> 138 # * Context: !in_interrupt()
>> 139 # *
>> 140 # * Some description
>> 141 # * Example:
>> 142 # * user_function(22);
>> 143 # */
>> 144 # ...
>> 145 #
>> 146 #
>> 147 # All descriptive text is further processed, scanning for the following special
>> 148 # patterns, which are highlighted appropriately.
>> 149 #
>> 150 # 'funcname()' - function
>> 151 # '$ENVVAR' - environmental variable
>> 152 # '&struct_name' - name of a structure (up to two words including 'struct')
>> 153 # '@parameter' - name of a parameter
>> 154 # '%CONST' - name of a constant.
58 155
59 my $errors = 0; 156 my $errors = 0;
60 my $warnings = 0; <<
61 my $anon_struct_union = 0; <<
62 157
63 # match expressions used to find embedded type 158 # match expressions used to find embedded type information
64 my $type_constant = '\b``([^\`]+)``\b'; !! 159 my $type_constant = '\%([-_\w]+)';
65 my $type_constant2 = '\%([-_*\w]+)'; <<
66 my $type_func = '(\w+)\(\)'; 160 my $type_func = '(\w+)\(\)';
67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\ !! 161 my $type_param = '\@(\w+)';
68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+) !! 162 my $type_struct = '\&((struct\s*)?[_\w]+)';
69 my $type_fp_param = '\@(\w+)\(\)'; # Special <<
70 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Sp <<
71 my $type_env = '(\$\w+)'; 163 my $type_env = '(\$\w+)';
72 my $type_enum = '\&(enum\s*([_\w]+))'; <<
73 my $type_struct = '\&(struct\s*([_\w]+))'; <<
74 my $type_typedef = '\&(typedef\s*([_\w]+))'; <<
75 my $type_union = '\&(union\s*([_\w]+))'; <<
76 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; <<
77 my $type_fallback = '\&([_\w]+)'; <<
78 my $type_member_func = $type_member . '\(\)'; <<
79 164
80 # Output conversion substitutions. 165 # Output conversion substitutions.
81 # One for each output format 166 # One for each output format
82 167
>> 168 # these work fairly well
>> 169 my %highlights_html = ( $type_constant, "<i>\$1</i>",
>> 170 $type_func, "<b>\$1</b>",
>> 171 $type_struct, "<i>\$1</i>",
>> 172 $type_param, "<tt><b>\$1</b></tt>" );
>> 173 my $blankline_html = "<p>";
>> 174
>> 175 # sgml, docbook format
>> 176 my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
>> 177 $type_constant, "<constant>\$1</constant>",
>> 178 $type_func, "<function>\$1</function>",
>> 179 $type_struct, "<structname>\$1</structname>",
>> 180 $type_env, "<envar>\$1</envar>",
>> 181 $type_param, "<parameter>\$1</parameter>" );
>> 182 my $blankline_sgml = "</para><para>\n";
>> 183
>> 184 # gnome, docbook format
>> 185 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
>> 186 $type_func, "<function>\$1</function>",
>> 187 $type_struct, "<structname>\$1</structname>",
>> 188 $type_env, "<envar>\$1</envar>",
>> 189 $type_param, "<parameter>\$1</parameter>" );
>> 190 my $blankline_gnome = "</para><para>\n";
>> 191
83 # these are pretty rough 192 # these are pretty rough
84 my @highlights_man = ( !! 193 my %highlights_man = ( $type_constant, "\$1",
85 [$type_constant, "\$1"], !! 194 $type_func, "\\\\fB\$1\\\\fP",
86 [$type_constant2, "\$1"], !! 195 $type_struct, "\\\\fI\$1\\\\fP",
87 [$type_func, "\\\\fB\$1\\\\fP"], !! 196 $type_param, "\\\\fI\$1\\\\fP" );
88 [$type_enum, "\\\\fI\$1\\\\fP"], <<
89 [$type_struct, "\\\\fI\$1\\\\fP"], <<
90 [$type_typedef, "\\\\fI\$1\\\\fP"], <<
91 [$type_union, "\\\\fI\$1\\\\fP"], <<
92 [$type_param, "\\\\fI\$1\\\\fP"], <<
93 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], <<
94 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], <<
95 [$type_fallback, "\\\\fI\$1\\\\fP"] <<
96 ); <<
97 my $blankline_man = ""; 197 my $blankline_man = "";
98 198
99 # rst-mode !! 199 # text-mode
100 my @highlights_rst = ( !! 200 my %highlights_text = ( $type_constant, "\$1",
101 [$type_constant, "``\$1``"], !! 201 $type_func, "\$1",
102 [$type_constant2, "``\$1``"], !! 202 $type_struct, "\$1",
103 !! 203 $type_param, "\$1" );
104 # Note: need to escape () to avoid func ma !! 204 my $blankline_text = "";
105 [$type_member_func, "\\:c\\:type\\:`\$1\$2 <<
106 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 < <<
107 [$type_fp_param, "**\$1\\\\(\\\\)**"], <<
108 [$type_fp_param2, "**\$1\\\\(\\\\)**"], <<
109 [$type_func, "\$1()"], <<
110 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], <<
111 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`" <<
112 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>` <<
113 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"] <<
114 <<
115 # in rst this can refer to any type <<
116 [$type_fallback, "\\:c\\:type\\:`\$1`"], <<
117 [$type_param_ref, "**\$1\$2**"] <<
118 ); <<
119 my $blankline_rst = "\n"; <<
120 205
121 # read arguments <<
122 if ($#ARGV == -1) { <<
123 pod2usage( <<
124 -message => "No arguments!\n", <<
125 -exitval => 1, <<
126 -verbose => 99, <<
127 -sections => 'SYNOPSIS', <<
128 -output => \*STDERR, <<
129 ); <<
130 } <<
131 206
132 my $kernelversion; !! 207 sub usage {
133 my ($sphinx_major, $sphinx_minor, $sphinx_patc !! 208 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
>> 209 print " [ -function funcname [ -function funcname ...] ]\n";
>> 210 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
>> 211 print " c source file(s) > outputfile\n";
>> 212 exit 1;
>> 213 }
134 214
135 my $dohighlight = ""; !! 215 # read arguments
>> 216 if ($#ARGV==-1) {
>> 217 usage();
>> 218 }
136 219
137 my $verbose = 0; 220 my $verbose = 0;
138 my $Werror = 0; !! 221 my $output_mode = "man";
139 my $Wreturn = 0; !! 222 my %highlights = %highlights_man;
140 my $Wshort_desc = 0; !! 223 my $blankline = $blankline_man;
141 my $Wcontents_before_sections = 0; <<
142 my $output_mode = "rst"; <<
143 my $output_preformatted = 0; <<
144 my $no_doc_sections = 0; <<
145 my $enable_lineno = 0; <<
146 my @highlights = @highlights_rst; <<
147 my $blankline = $blankline_rst; <<
148 my $modulename = "Kernel API"; 224 my $modulename = "Kernel API";
149 !! 225 my $function_only = 0;
150 use constant { !! 226 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
151 OUTPUT_ALL => 0, # output all sym !! 227 'July', 'August', 'September', 'October',
152 OUTPUT_INCLUDE => 1, # output only sp !! 228 'November', 'December')[(localtime)[4]] .
153 OUTPUT_EXPORTED => 2, # output exporte !! 229 " " . ((localtime)[5]+1900);
154 OUTPUT_INTERNAL => 3, # output non-exp !! 230
155 }; !! 231 # Essentially these are globals
156 my $output_selection = OUTPUT_ALL; !! 232 # They probably want to be tidied up made more localised or summat.
157 my $show_not_found = 0; # No longer used !! 233 # CAVEAT EMPTOR! Some of the others I localised may not want to be which
158 <<
159 my @export_file_list; <<
160 <<
161 my @build_time; <<
162 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && <<
163 (my $seconds = `date -d"${ENV{'KBUILD_BUIL <<
164 @build_time = gmtime($seconds); <<
165 } else { <<
166 @build_time = localtime; <<
167 } <<
168 <<
169 my $man_date = ('January', 'February', 'March' <<
170 'July', 'August', 'September', <<
171 'November', 'December')[$build <<
172 " " . ($build_time[5]+1900); <<
173 <<
174 # Essentially these are globals. <<
175 # They probably want to be tidied up, made mor <<
176 # CAVEAT EMPTOR! Some of the others I localis <<
177 # could cause "use of undefined value" or othe 234 # could cause "use of undefined value" or other bugs.
178 my ($function, %function_table, %parametertype !! 235 my ($function, %function_table,%parametertypes,$declaration_purpose);
179 my %nosymbol_table = (); !! 236 my ($type,$declaration_name,$return_type);
180 my $declaration_start_line; !! 237 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
181 my ($type, $declaration_name, $return_type); <<
182 my ($newsection, $newcontents, $prototype, $br <<
183 <<
184 if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'K <<
185 $verbose = 1; <<
186 } <<
187 <<
188 if (defined($ENV{'KCFLAGS'})) { <<
189 my $kcflags = "$ENV{'KCFLAGS'}"; <<
190 <<
191 if ($kcflags =~ /(\s|^)-Werror(\s|$)/) { <<
192 $Werror = 1; <<
193 } <<
194 } <<
195 238
196 # reading this variable is for backwards compa !! 239 # Generated docbook code is inserted in a template at a point where
197 # someone was calling it with the variable fro <<
198 # kernel's build system <<
199 if (defined($ENV{'KDOC_WERROR'})) { <<
200 $Werror = "$ENV{'KDOC_WERROR'}"; <<
201 } <<
202 # other environment variables are converted to <<
203 # arguments in cmd_checkdoc in the build syste <<
204 <<
205 # Generated docbook code is inserted in a temp <<
206 # docbook v3.1 requires a non-zero sequence of 240 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
207 # https://www.oasis-open.org/docbook/documenta !! 241 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
208 # We keep track of number of generated entries 242 # We keep track of number of generated entries and generate a dummy
209 # if needs be to ensure the expanded template 243 # if needs be to ensure the expanded template can be postprocessed
210 # into html. 244 # into html.
211 my $section_counter = 0; 245 my $section_counter = 0;
212 246
213 my $lineprefix=""; 247 my $lineprefix="";
214 248
215 # Parser states !! 249 # states
216 use constant { !! 250 # 0 - normal code
217 STATE_NORMAL => 0, # normal !! 251 # 1 - looking for function name
218 STATE_NAME => 1, # looking !! 252 # 2 - scanning field start.
219 STATE_BODY_MAYBE => 2, # body - !! 253 # 3 - scanning prototype.
220 STATE_BODY => 3, # the bod !! 254 # 4 - documentation block
221 STATE_BODY_WITH_BLANK_LINE => 4, # the bod <<
222 STATE_PROTO => 5, # scannin <<
223 STATE_DOCBLOCK => 6, # documen <<
224 STATE_INLINE => 7, # gatheri <<
225 }; <<
226 my $state; 255 my $state;
227 my $in_doc_sect; <<
228 my $leading_space; <<
229 <<
230 # Inline documentation state <<
231 use constant { <<
232 STATE_INLINE_NA => 0, # not applicable <<
233 STATE_INLINE_NAME => 1, # looking for me <<
234 STATE_INLINE_TEXT => 2, # looking for me <<
235 STATE_INLINE_END => 3, # done <<
236 STATE_INLINE_ERROR => 4, # error - Commen <<
237 # Spit a warning <<
238 # proper kernel- <<
239 }; <<
240 my $inline_doc_state; <<
241 256
242 #declaration types: can be 257 #declaration types: can be
243 # 'function', 'struct', 'union', 'enum', 'type 258 # 'function', 'struct', 'union', 'enum', 'typedef'
244 my $decl_type; 259 my $decl_type;
245 260
246 # Name of the kernel-doc identifier for non-DO !! 261 my $doc_special = "\@\%\$\&";
247 my $identifier; <<
248 262
249 my $doc_start = '^/\*\*\s*$'; # Allow whitespa 263 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
250 my $doc_end = '\*/'; 264 my $doc_end = '\*/';
251 my $doc_com = '\s*\*\s*'; 265 my $doc_com = '\s*\*\s*';
252 my $doc_com_body = '\s*\* ?'; !! 266 my $doc_decl = $doc_com.'(\w+)';
253 my $doc_decl = $doc_com . '(\w+)'; !! 267 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
254 # @params and a strictly limited set of suppor !! 268 my $doc_content = $doc_com.'(.*)';
255 # Specifically: !! 269 my $doc_block = $doc_com.'DOC:\s*(.*)?';
256 # Match @word: <<
257 # @...: <<
258 # @{section-name}: <<
259 # while trying to not match literal block star <<
260 # <<
261 my $doc_sect = $doc_com . <<
262 '\s*(\@[.\w]+|\@\.\.\.|description|context <<
263 my $doc_content = $doc_com_body . '(.*)'; <<
264 my $doc_block = $doc_com . 'DOC:\s*(.*)?'; <<
265 my $doc_inline_start = '^\s*/\*\*\s*$'; <<
266 my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.] <<
267 my $doc_inline_end = '^\s*\*/\s*$'; <<
268 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s] <<
269 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\ <<
270 my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_ <<
271 my $function_pointer = qr{([^\(]*\(\*)\s*\)\s* <<
272 my $attribute = qr{__attribute__\s*\(\([a-z0-9 <<
273 270
>> 271 my %constants;
274 my %parameterdescs; 272 my %parameterdescs;
275 my %parameterdesc_start_lines; <<
276 my @parameterlist; 273 my @parameterlist;
277 my %sections; 274 my %sections;
278 my @sectionlist; 275 my @sectionlist;
279 my %section_start_lines; <<
280 my $sectcheck; <<
281 my $struct_actual; <<
282 276
283 my $contents = ""; 277 my $contents = "";
284 my $new_start_line = 0; <<
285 <<
286 # the canonical section names. see also $doc_s <<
287 my $section_default = "Description"; # defa 278 my $section_default = "Description"; # default section
288 my $section_intro = "Introduction"; 279 my $section_intro = "Introduction";
289 my $section = $section_default; 280 my $section = $section_default;
290 my $section_context = "Context"; 281 my $section_context = "Context";
291 my $section_return = "Return"; <<
292 282
293 my $undescribed = "-- undescribed --"; 283 my $undescribed = "-- undescribed --";
294 284
295 reset_state(); 285 reset_state();
296 286
297 while ($ARGV[0] =~ m/^--?(.*)/) { !! 287 while ($ARGV[0] =~ m/^-(.*)/) {
298 my $cmd = $1; !! 288 my $cmd = shift @ARGV;
299 shift @ARGV; !! 289 if ($cmd eq "-html") {
300 if ($cmd eq "man") { !! 290 $output_mode = "html";
301 $output_mode = "man"; !! 291 %highlights = %highlights_html;
302 @highlights = @highlights_man; !! 292 $blankline = $blankline_html;
303 $blankline = $blankline_man; !! 293 } elsif ($cmd eq "-man") {
304 } elsif ($cmd eq "rst") { !! 294 $output_mode = "man";
305 $output_mode = "rst"; !! 295 %highlights = %highlights_man;
306 @highlights = @highlights_rst; !! 296 $blankline = $blankline_man;
307 $blankline = $blankline_rst; !! 297 } elsif ($cmd eq "-text") {
308 } elsif ($cmd eq "none") { !! 298 $output_mode = "text";
309 $output_mode = "none"; !! 299 %highlights = %highlights_text;
310 } elsif ($cmd eq "module") { # not needed !! 300 $blankline = $blankline_text;
311 $modulename = shift @ARGV; !! 301 } elsif ($cmd eq "-docbook") {
312 } elsif ($cmd eq "function") { # to only o !! 302 $output_mode = "sgml";
313 $output_selection = OUTPUT_INCLUDE; !! 303 %highlights = %highlights_sgml;
314 $function = shift @ARGV; !! 304 $blankline = $blankline_sgml;
315 $function_table{$function} = 1; !! 305 } elsif ($cmd eq "-gnome") {
316 } elsif ($cmd eq "nosymbol") { # Exclude s !! 306 $output_mode = "gnome";
317 my $symbol = shift @ARGV; !! 307 %highlights = %highlights_gnome;
318 $nosymbol_table{$symbol} = 1; !! 308 $blankline = $blankline_gnome;
319 } elsif ($cmd eq "export") { # only export !! 309 } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
320 $output_selection = OUTPUT_EXPORTED; !! 310 $modulename = shift @ARGV;
321 %function_table = (); !! 311 } elsif ($cmd eq "-function") { # to only output specific functions
322 } elsif ($cmd eq "internal") { # only non- !! 312 $function_only = 1;
323 $output_selection = OUTPUT_INTERNAL; !! 313 $function = shift @ARGV;
324 %function_table = (); !! 314 $function_table{$function} = 1;
325 } elsif ($cmd eq "export-file") { !! 315 } elsif ($cmd eq "-nofunction") { # to only output specific functions
326 my $file = shift @ARGV; !! 316 $function_only = 2;
327 push(@export_file_list, $file); !! 317 $function = shift @ARGV;
328 } elsif ($cmd eq "v") { !! 318 $function_table{$function} = 1;
329 $verbose = 1; !! 319 } elsif ($cmd eq "-v") {
330 } elsif ($cmd eq "Werror") { !! 320 $verbose = 1;
331 $Werror = 1; !! 321 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
332 } elsif ($cmd eq "Wreturn") { !! 322 usage();
333 $Wreturn = 1; !! 323 } elsif ($cmd eq '-filelist') {
334 } elsif ($cmd eq "Wshort-desc" or $cmd eq !! 324 $filelist = shift @ARGV;
335 $Wshort_desc = 1; <<
336 } elsif ($cmd eq "Wcontents-before-section <<
337 $Wcontents_before_sections = 1; <<
338 } elsif ($cmd eq "Wall") { <<
339 $Wreturn = 1; <<
340 $Wshort_desc = 1; <<
341 $Wcontents_before_sections = 1; <<
342 } elsif (($cmd eq "h") || ($cmd eq "help") <<
343 pod2usage(-exitval => 0, -verbose => 2 <<
344 } elsif ($cmd eq 'no-doc-sections') { <<
345 $no_doc_sections = 1; <<
346 } elsif ($cmd eq 'enable-lineno') { <<
347 $enable_lineno = 1; <<
348 } elsif ($cmd eq 'show-not-found') { <<
349 $show_not_found = 1; # A no-op but do <<
350 } elsif ($cmd eq "sphinx-version") { <<
351 my $ver_string = shift @ARGV; <<
352 if ($ver_string =~ m/^(\d+)(\.\d+)?(\. <<
353 $sphinx_major = $1; <<
354 if (defined($2)) { <<
355 $sphinx_minor = substr($2,1); <<
356 } else { <<
357 $sphinx_minor = 0; <<
358 } <<
359 if (defined($3)) { <<
360 $sphinx_patch = substr($3,1) <<
361 } else { <<
362 $sphinx_patch = 0; <<
363 } <<
364 } else { <<
365 die "Sphinx version should either <<
366 } <<
367 } else { <<
368 # Unknown argument <<
369 pod2usage( <<
370 -message => "Argument unknown!\n", <<
371 -exitval => 1, <<
372 -verbose => 99, <<
373 -sections => 'SYNOPSIS', <<
374 -output => \*STDERR, <<
375 ); <<
376 } <<
377 if ($#ARGV < 0){ <<
378 pod2usage( <<
379 -message => "FILE argument missing <<
380 -exitval => 1, <<
381 -verbose => 99, <<
382 -sections => 'SYNOPSIS', <<
383 -output => \*STDERR, <<
384 ); <<
385 } <<
386 } <<
387 <<
388 # continue execution near EOF; <<
389 <<
390 # The C domain dialect changed on Sphinx 3. So <<
391 # version in order to produce the right tags. <<
392 sub findprog($) <<
393 { <<
394 foreach(split(/:/, $ENV{PATH})) { <<
395 return "$_/$_[0]" if(-x "$_/$_[0]"); <<
396 } 325 }
397 } 326 }
398 327
399 sub get_sphinx_version() <<
400 { <<
401 my $ver; <<
402 <<
403 my $cmd = "sphinx-build"; <<
404 if (!findprog($cmd)) { <<
405 my $cmd = "sphinx-build3"; <<
406 if (!findprog($cmd)) { <<
407 $sphinx_major = 1; <<
408 $sphinx_minor = 2; <<
409 $sphinx_patch = 0; <<
410 printf STDERR "Warning: Sphinx ver <<
411 $sphinx_major, $sphinx_mino <<
412 return; <<
413 } <<
414 } <<
415 328
416 open IN, "$cmd --version 2>&1 |"; !! 329 # generate a sequence of code that will splice in highlighting information
417 while (<IN>) { !! 330 # using the s// operator.
418 if (m/^\s*sphinx-build\s+([\d]+)\.([\d !! 331 my $dohighlight = "";
419 $sphinx_major = $1; !! 332 foreach my $pattern (keys %highlights) {
420 $sphinx_minor = $2; !! 333 # print "scanning pattern $pattern ($highlights{$pattern})\n";
421 $sphinx_patch = $3; !! 334 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
422 last; <<
423 } <<
424 # Sphinx 1.2.x uses a different format <<
425 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+ <<
426 $sphinx_major = $1; <<
427 $sphinx_minor = $2; <<
428 $sphinx_patch = $3; <<
429 last; <<
430 } <<
431 } <<
432 close IN; <<
433 } <<
434 <<
435 # get kernel version from env <<
436 sub get_kernel_version() { <<
437 my $version = 'unknown kernel version'; <<
438 <<
439 if (defined($ENV{'KERNELVERSION'})) { <<
440 $version = $ENV{'KERNELVERSION'}; <<
441 } <<
442 return $version; <<
443 } <<
444 <<
445 # <<
446 sub print_lineno { <<
447 my $lineno = shift; <<
448 if ($enable_lineno && defined($lineno)) { <<
449 print ".. LINENO " . $lineno . "\n"; <<
450 } <<
451 } 335 }
452 336
453 sub emit_warning { <<
454 my $location = shift; <<
455 my $msg = shift; <<
456 print STDERR "$location: warning: $msg"; <<
457 ++$warnings; <<
458 } <<
459 ## 337 ##
460 # dumps section contents to arrays/hashes inte 338 # dumps section contents to arrays/hashes intended for that purpose.
461 # 339 #
462 sub dump_section { 340 sub dump_section {
463 my $file = shift; <<
464 my $name = shift; 341 my $name = shift;
465 my $contents = join "\n", @_; 342 my $contents = join "\n", @_;
466 343
467 if ($name =~ m/$type_param/) { !! 344 if ($name =~ m/$type_constant/) {
468 $name = $1; !! 345 $name = $1;
469 $parameterdescs{$name} = $contents; !! 346 # print STDERR "constant section '$1' = '$contents'\n";
470 $sectcheck = $sectcheck . $name . " "; !! 347 $constants{$name} = $contents;
471 $parameterdesc_start_lines{$name} = $n !! 348 } elsif ($name =~ m/$type_param/) {
472 $new_start_line = 0; !! 349 # print STDERR "parameter def '$1' = '$contents'\n";
473 } elsif ($name eq "@\.\.\.") { !! 350 $name = $1;
474 $name = "..."; !! 351 $parameterdescs{$name} = $contents;
475 $parameterdescs{$name} = $contents; <<
476 $sectcheck = $sectcheck . $name . " "; <<
477 $parameterdesc_start_lines{$name} = $n <<
478 $new_start_line = 0; <<
479 } else { 352 } else {
480 if (defined($sections{$name}) && ($sec !! 353 # print STDERR "other section '$name' = '$contents'\n";
481 # Only warn on user specified dupl !! 354 $sections{$name} = $contents;
482 if ($name ne $section_default) { !! 355 push @sectionlist, $name;
483 emit_warning("${file}:$.", "du <<
484 } <<
485 $sections{$name} .= $contents; <<
486 } else { <<
487 $sections{$name} = $contents; <<
488 push @sectionlist, $name; <<
489 $section_start_lines{$name} = $new <<
490 $new_start_line = 0; <<
491 } <<
492 } <<
493 } <<
494 <<
495 ## <<
496 # dump DOC: section after checking that it sho <<
497 # <<
498 sub dump_doc_section { <<
499 my $file = shift; <<
500 my $name = shift; <<
501 my $contents = join "\n", @_; <<
502 <<
503 if ($no_doc_sections) { <<
504 return; <<
505 } <<
506 <<
507 return if (defined($nosymbol_table{$name}) <<
508 <<
509 if (($output_selection == OUTPUT_ALL) || <<
510 (($output_selection == OUTPUT_INCLUDE) <<
511 defined($function_table{$name}))) <<
512 { <<
513 dump_section($file, $name, $contents); <<
514 output_blockhead({'sectionlist' => \@s <<
515 'sections' => \%sect <<
516 'module' => $modulen <<
517 'content-only' => ($ <<
518 } 356 }
519 } 357 }
520 358
521 ## 359 ##
522 # output function 360 # output function
523 # 361 #
524 # parameterdescs, a hash. 362 # parameterdescs, a hash.
525 # function => "function name" 363 # function => "function name"
526 # parameterlist => @list of parameters 364 # parameterlist => @list of parameters
527 # parameterdescs => %parameter descriptions 365 # parameterdescs => %parameter descriptions
528 # sectionlist => @list of sections 366 # sectionlist => @list of sections
529 # sections => %section descriptions !! 367 # sections => %descriont descriptions
530 # !! 368 #
531 369
532 sub output_highlight { 370 sub output_highlight {
533 my $contents = join "\n",@_; 371 my $contents = join "\n",@_;
534 my $line; 372 my $line;
535 373
536 # DEBUG 374 # DEBUG
537 # if (!defined $contents) { 375 # if (!defined $contents) {
538 # use Carp; 376 # use Carp;
539 # confess "output_highlight got called w 377 # confess "output_highlight got called with no args?\n";
540 # } 378 # }
541 379
542 # print STDERR "contents b4:$contents\n"; <<
543 eval $dohighlight; 380 eval $dohighlight;
544 die $@ if $@; 381 die $@ if $@;
545 # print STDERR "contents af:$contents\n"; <<
546 <<
547 foreach $line (split "\n", $contents) { 382 foreach $line (split "\n", $contents) {
548 if (! $output_preformatted) { !! 383 if ($line eq ""){
549 $line =~ s/^\s*//; !! 384 print $lineprefix, $blankline;
550 } !! 385 } else {
551 if ($line eq ""){ !! 386 $line =~ s/\\\\\\/\&/g;
552 if (! $output_preformatted) { !! 387 print $lineprefix, $line;
553 print $lineprefix, $blankline; !! 388 }
554 } !! 389 print "\n";
555 } else { !! 390 }
556 if ($output_mode eq "man" && subst !! 391 }
557 print "\\&$line"; !! 392
558 } else { !! 393 #output sections in html
559 print $lineprefix, $line; !! 394 sub output_section_html(%) {
560 } !! 395 my %args = %{$_[0]};
561 } !! 396 my $section;
562 print "\n"; !! 397
>> 398 foreach $section (@{$args{'sectionlist'}}) {
>> 399 print "<h3>$section</h3>\n";
>> 400 print "<blockquote>\n";
>> 401 output_highlight($args{'sections'}{$section});
>> 402 print "</blockquote>\n";
>> 403 }
>> 404 }
>> 405
>> 406 # output enum in html
>> 407 sub output_enum_html(%) {
>> 408 my %args = %{$_[0]};
>> 409 my ($parameter);
>> 410 my $count;
>> 411 print "<h2>enum ".$args{'enum'}."</h2>\n";
>> 412
>> 413 print "<b>enum ".$args{'enum'}."</b> {<br>\n";
>> 414 $count = 0;
>> 415 foreach $parameter (@{$args{'parameterlist'}}) {
>> 416 print " <b>".$parameter."</b>";
>> 417 if ($count != $#{$args{'parameterlist'}}) {
>> 418 $count++;
>> 419 print ",\n";
>> 420 }
>> 421 print "<br>";
>> 422 }
>> 423 print "};<br>\n";
>> 424
>> 425 print "<h3>Constants</h3>\n";
>> 426 print "<dl>\n";
>> 427 foreach $parameter (@{$args{'parameterlist'}}) {
>> 428 print "<dt><b>".$parameter."</b>\n";
>> 429 print "<dd>";
>> 430 output_highlight($args{'parameterdescs'}{$parameter});
>> 431 }
>> 432 print "</dl>\n";
>> 433 output_section_html(@_);
>> 434 print "<hr>\n";
>> 435 }
>> 436
>> 437 # output tyepdef in html
>> 438 sub output_typedef_html(%) {
>> 439 my %args = %{$_[0]};
>> 440 my ($parameter);
>> 441 my $count;
>> 442 print "<h2>typedef ".$args{'typedef'}."</h2>\n";
>> 443
>> 444 print "<b>typedef ".$args{'typedef'}."</b>\n";
>> 445 output_section_html(@_);
>> 446 print "<hr>\n";
>> 447 }
>> 448
>> 449 # output struct in html
>> 450 sub output_struct_html(%) {
>> 451 my %args = %{$_[0]};
>> 452 my ($parameter);
>> 453
>> 454 print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
>> 455 print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
>> 456 foreach $parameter (@{$args{'parameterlist'}}) {
>> 457 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 458 $type = $args{'parametertypes'}{$parameter};
>> 459 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 460 # pointer-to-function
>> 461 print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
>> 462 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 463 print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
>> 464 } else {
>> 465 print " <i>$type</i> <b>$parameter</b>;<br>\n";
>> 466 }
>> 467 }
>> 468 print "};<br>\n";
>> 469
>> 470 print "<h3>Members</h3>\n";
>> 471 print "<dl>\n";
>> 472 foreach $parameter (@{$args{'parameterlist'}}) {
>> 473 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 474 print "<dt><b>".$parameter."</b>\n";
>> 475 print "<dd>";
>> 476 output_highlight($args{'parameterdescs'}{$parameter});
>> 477 }
>> 478 print "</dl>\n";
>> 479 output_section_html(@_);
>> 480 print "<hr>\n";
>> 481 }
>> 482
>> 483 # output function in html
>> 484 sub output_function_html(%) {
>> 485 my %args = %{$_[0]};
>> 486 my ($parameter, $section);
>> 487 my $count;
>> 488 print "<h2>Function</h2>\n";
>> 489
>> 490 print "<i>".$args{'functiontype'}."</i>\n";
>> 491 print "<b>".$args{'function'}."</b>\n";
>> 492 print "(";
>> 493 $count = 0;
>> 494 foreach $parameter (@{$args{'parameterlist'}}) {
>> 495 $type = $args{'parametertypes'}{$parameter};
>> 496 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 497 # pointer-to-function
>> 498 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
>> 499 } else {
>> 500 print "<i>".$type."</i> <b>".$parameter."</b>";
>> 501 }
>> 502 if ($count != $#{$args{'parameterlist'}}) {
>> 503 $count++;
>> 504 print ",\n";
>> 505 }
>> 506 }
>> 507 print ")\n";
>> 508
>> 509 print "<h3>Arguments</h3>\n";
>> 510 print "<dl>\n";
>> 511 foreach $parameter (@{$args{'parameterlist'}}) {
>> 512 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 513 print "<dt><b>".$parameter."</b>\n";
>> 514 print "<dd>";
>> 515 output_highlight($args{'parameterdescs'}{$parameter});
>> 516 }
>> 517 print "</dl>\n";
>> 518 output_section_html(@_);
>> 519 print "<hr>\n";
>> 520 }
>> 521
>> 522 # output intro in html
>> 523 sub output_intro_html(%) {
>> 524 my %args = %{$_[0]};
>> 525 my ($parameter, $section);
>> 526 my $count;
>> 527
>> 528 foreach $section (@{$args{'sectionlist'}}) {
>> 529 print "<h3>$section</h3>\n";
>> 530 print "<ul>\n";
>> 531 output_highlight($args{'sections'}{$section});
>> 532 print "</ul>\n";
>> 533 }
>> 534 print "<hr>\n";
>> 535 }
>> 536
>> 537 sub output_section_sgml(%) {
>> 538 my %args = %{$_[0]};
>> 539 my $section;
>> 540 # print out each section
>> 541 $lineprefix=" ";
>> 542 foreach $section (@{$args{'sectionlist'}}) {
>> 543 print "<refsect1>\n <title>$section</title>\n <para>\n";
>> 544 if ($section =~ m/EXAMPLE/i) {
>> 545 print "<example><para>\n";
>> 546 }
>> 547 output_highlight($args{'sections'}{$section});
>> 548 if ($section =~ m/EXAMPLE/i) {
>> 549 print "</para></example>\n";
>> 550 }
>> 551 print " </para>\n</refsect1>\n";
>> 552 }
>> 553 }
>> 554
>> 555 # output function in sgml DocBook
>> 556 sub output_function_sgml(%) {
>> 557 my %args = %{$_[0]};
>> 558 my ($parameter, $section);
>> 559 my $count;
>> 560 my $id;
>> 561
>> 562 $id = "API-".$args{'function'};
>> 563 $id =~ s/[^A-Za-z0-9]/-/g;
>> 564
>> 565 print "<refentry>\n";
>> 566 print "<refmeta>\n";
>> 567 print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
>> 568 print "</refmeta>\n";
>> 569 print "<refnamediv>\n";
>> 570 print " <refname>".$args{'function'}."</refname>\n";
>> 571 print " <refpurpose>\n";
>> 572 print " ";
>> 573 output_highlight ($args{'purpose'});
>> 574 print " </refpurpose>\n";
>> 575 print "</refnamediv>\n";
>> 576
>> 577 print "<refsynopsisdiv>\n";
>> 578 print " <title>Synopsis</title>\n";
>> 579 print " <funcsynopsis><funcprototype>\n";
>> 580 print " <funcdef>".$args{'functiontype'}." ";
>> 581 print "<function>".$args{'function'}." </function></funcdef>\n";
>> 582
>> 583 $count = 0;
>> 584 if ($#{$args{'parameterlist'}} >= 0) {
>> 585 foreach $parameter (@{$args{'parameterlist'}}) {
>> 586 $type = $args{'parametertypes'}{$parameter};
>> 587 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 588 # pointer-to-function
>> 589 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
>> 590 print " <funcparams>$2</funcparams></paramdef>\n";
>> 591 } else {
>> 592 print " <paramdef>".$type;
>> 593 print " <parameter>$parameter</parameter></paramdef>\n";
>> 594 }
>> 595 }
>> 596 } else {
>> 597 print " <void>\n";
>> 598 }
>> 599 print " </funcprototype></funcsynopsis>\n";
>> 600 print "</refsynopsisdiv>\n";
>> 601
>> 602 # print parameters
>> 603 print "<refsect1>\n <title>Arguments</title>\n";
>> 604 if ($#{$args{'parameterlist'}} >= 0) {
>> 605 print " <variablelist>\n";
>> 606 foreach $parameter (@{$args{'parameterlist'}}) {
>> 607 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
>> 608 print " <listitem>\n <para>\n";
>> 609 $lineprefix=" ";
>> 610 output_highlight($args{'parameterdescs'}{$parameter});
>> 611 print " </para>\n </listitem>\n </varlistentry>\n";
>> 612 }
>> 613 print " </variablelist>\n";
>> 614 } else {
>> 615 print " <para>\n None\n </para>\n";
>> 616 }
>> 617 print "</refsect1>\n";
>> 618
>> 619 output_section_sgml(@_);
>> 620 print "</refentry>\n\n";
>> 621 }
>> 622
>> 623 # output struct in sgml DocBook
>> 624 sub output_struct_sgml(%) {
>> 625 my %args = %{$_[0]};
>> 626 my ($parameter, $section);
>> 627 my $id;
>> 628
>> 629 $id = "API-struct-".$args{'struct'};
>> 630 $id =~ s/[^A-Za-z0-9]/-/g;
>> 631
>> 632 print "<refentry>\n";
>> 633 print "<refmeta>\n";
>> 634 print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
>> 635 print "</refmeta>\n";
>> 636 print "<refnamediv>\n";
>> 637 print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
>> 638 print " <refpurpose>\n";
>> 639 print " ";
>> 640 output_highlight ($args{'purpose'});
>> 641 print " </refpurpose>\n";
>> 642 print "</refnamediv>\n";
>> 643
>> 644 print "<refsynopsisdiv>\n";
>> 645 print " <title>Synopsis</title>\n";
>> 646 print " <programlisting>\n";
>> 647 print $args{'type'}." ".$args{'struct'}." {\n";
>> 648 foreach $parameter (@{$args{'parameterlist'}}) {
>> 649 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 650 $type = $args{'parametertypes'}{$parameter};
>> 651 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 652 # pointer-to-function
>> 653 print " $1 $parameter ($2);\n";
>> 654 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 655 print " $1 $parameter$2;\n";
>> 656 } else {
>> 657 print " ".$type." ".$parameter.";\n";
>> 658 }
>> 659 }
>> 660 print "};";
>> 661 print " </programlisting>\n";
>> 662 print "</refsynopsisdiv>\n";
>> 663
>> 664 print " <refsect1>\n";
>> 665 print " <title>Members</title>\n";
>> 666
>> 667 print " <variablelist>\n";
>> 668 foreach $parameter (@{$args{'parameterlist'}}) {
>> 669 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 670 print " <varlistentry>";
>> 671 print " <term>$parameter</term>\n";
>> 672 print " <listitem><para>\n";
>> 673 output_highlight($args{'parameterdescs'}{$parameter});
>> 674 print " </para></listitem>\n";
>> 675 print " </varlistentry>\n";
>> 676 }
>> 677 print " </variablelist>\n";
>> 678 print " </refsect1>\n";
>> 679
>> 680 output_section_sgml(@_);
>> 681
>> 682 print "</refentry>\n\n";
>> 683 }
>> 684
>> 685 # output enum in sgml DocBook
>> 686 sub output_enum_sgml(%) {
>> 687 my %args = %{$_[0]};
>> 688 my ($parameter, $section);
>> 689 my $count;
>> 690 my $id;
>> 691
>> 692 $id = "API-enum-".$args{'enum'};
>> 693 $id =~ s/[^A-Za-z0-9]/-/g;
>> 694
>> 695 print "<refentry>\n";
>> 696 print "<refmeta>\n";
>> 697 print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
>> 698 print "</refmeta>\n";
>> 699 print "<refnamediv>\n";
>> 700 print " <refname>enum ".$args{'enum'}."</refname>\n";
>> 701 print " <refpurpose>\n";
>> 702 print " ";
>> 703 output_highlight ($args{'purpose'});
>> 704 print " </refpurpose>\n";
>> 705 print "</refnamediv>\n";
>> 706
>> 707 print "<refsynopsisdiv>\n";
>> 708 print " <title>Synopsis</title>\n";
>> 709 print " <programlisting>\n";
>> 710 print "enum ".$args{'enum'}." {\n";
>> 711 $count = 0;
>> 712 foreach $parameter (@{$args{'parameterlist'}}) {
>> 713 print " $parameter";
>> 714 if ($count != $#{$args{'parameterlist'}}) {
>> 715 $count++;
>> 716 print ",";
>> 717 }
>> 718 print "\n";
>> 719 }
>> 720 print "};";
>> 721 print " </programlisting>\n";
>> 722 print "</refsynopsisdiv>\n";
>> 723
>> 724 print "<refsect1>\n";
>> 725 print " <title>Constants</title>\n";
>> 726 print " <variablelist>\n";
>> 727 foreach $parameter (@{$args{'parameterlist'}}) {
>> 728 print " <varlistentry>";
>> 729 print " <term>$parameter</term>\n";
>> 730 print " <listitem><para>\n";
>> 731 output_highlight($args{'parameterdescs'}{$parameter});
>> 732 print " </para></listitem>\n";
>> 733 print " </varlistentry>\n";
>> 734 }
>> 735 print " </variablelist>\n";
>> 736 print "</refsect1>\n";
>> 737
>> 738 output_section_sgml(@_);
>> 739
>> 740 print "</refentry>\n\n";
>> 741 }
>> 742
>> 743 # output typedef in sgml DocBook
>> 744 sub output_typedef_sgml(%) {
>> 745 my %args = %{$_[0]};
>> 746 my ($parameter, $section);
>> 747 my $id;
>> 748
>> 749 $id = "API-typedef-".$args{'typedef'};
>> 750 $id =~ s/[^A-Za-z0-9]/-/g;
>> 751
>> 752 print "<refentry>\n";
>> 753 print "<refmeta>\n";
>> 754 print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
>> 755 print "</refmeta>\n";
>> 756 print "<refnamediv>\n";
>> 757 print " <refname>typedef ".$args{'typedef'}."</refname>\n";
>> 758 print " <refpurpose>\n";
>> 759 print " ";
>> 760 output_highlight ($args{'purpose'});
>> 761 print " </refpurpose>\n";
>> 762 print "</refnamediv>\n";
>> 763
>> 764 print "<refsynopsisdiv>\n";
>> 765 print " <title>Synopsis</title>\n";
>> 766 print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
>> 767 print "</refsynopsisdiv>\n";
>> 768
>> 769 output_section_sgml(@_);
>> 770
>> 771 print "</refentry>\n\n";
>> 772 }
>> 773
>> 774 # output in sgml DocBook
>> 775 sub output_intro_sgml(%) {
>> 776 my %args = %{$_[0]};
>> 777 my ($parameter, $section);
>> 778 my $count;
>> 779
>> 780 my $id = $args{'module'};
>> 781 $id =~ s/[^A-Za-z0-9]/-/g;
>> 782
>> 783 # print out each section
>> 784 $lineprefix=" ";
>> 785 foreach $section (@{$args{'sectionlist'}}) {
>> 786 print "<refsect1>\n <title>$section</title>\n <para>\n";
>> 787 if ($section =~ m/EXAMPLE/i) {
>> 788 print "<example><para>\n";
>> 789 }
>> 790 output_highlight($args{'sections'}{$section});
>> 791 if ($section =~ m/EXAMPLE/i) {
>> 792 print "</para></example>\n";
>> 793 }
>> 794 print " </para>\n</refsect1>\n";
>> 795 }
>> 796
>> 797 print "\n\n";
>> 798 }
>> 799
>> 800 # output in sgml DocBook
>> 801 sub output_function_gnome {
>> 802 my %args = %{$_[0]};
>> 803 my ($parameter, $section);
>> 804 my $count;
>> 805 my $id;
>> 806
>> 807 $id = $args{'module'}."-".$args{'function'};
>> 808 $id =~ s/[^A-Za-z0-9]/-/g;
>> 809
>> 810 print "<sect2>\n";
>> 811 print " <title id=\"$id\">".$args{'function'}."</title>\n";
>> 812
>> 813 print " <funcsynopsis>\n";
>> 814 print " <funcdef>".$args{'functiontype'}." ";
>> 815 print "<function>".$args{'function'}." ";
>> 816 print "</function></funcdef>\n";
>> 817
>> 818 $count = 0;
>> 819 if ($#{$args{'parameterlist'}} >= 0) {
>> 820 foreach $parameter (@{$args{'parameterlist'}}) {
>> 821 $type = $args{'parametertypes'}{$parameter};
>> 822 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 823 # pointer-to-function
>> 824 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
>> 825 print " <funcparams>$2</funcparams></paramdef>\n";
>> 826 } else {
>> 827 print " <paramdef>".$type;
>> 828 print " <parameter>$parameter</parameter></paramdef>\n";
>> 829 }
>> 830 }
>> 831 } else {
>> 832 print " <void>\n";
>> 833 }
>> 834 print " </funcsynopsis>\n";
>> 835 if ($#{$args{'parameterlist'}} >= 0) {
>> 836 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
>> 837 print "<tgroup cols=\"2\">\n";
>> 838 print "<colspec colwidth=\"2*\">\n";
>> 839 print "<colspec colwidth=\"8*\">\n";
>> 840 print "<tbody>\n";
>> 841 foreach $parameter (@{$args{'parameterlist'}}) {
>> 842 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
>> 843 print " <entry>\n";
>> 844 $lineprefix=" ";
>> 845 output_highlight($args{'parameterdescs'}{$parameter});
>> 846 print " </entry></row>\n";
>> 847 }
>> 848 print " </tbody></tgroup></informaltable>\n";
>> 849 } else {
>> 850 print " <para>\n None\n </para>\n";
563 } 851 }
>> 852
>> 853 # print out each section
>> 854 $lineprefix=" ";
>> 855 foreach $section (@{$args{'sectionlist'}}) {
>> 856 print "<simplesect>\n <title>$section</title>\n";
>> 857 if ($section =~ m/EXAMPLE/i) {
>> 858 print "<example><programlisting>\n";
>> 859 } else {
>> 860 }
>> 861 print "<para>\n";
>> 862 output_highlight($args{'sections'}{$section});
>> 863 print "</para>\n";
>> 864 if ($section =~ m/EXAMPLE/i) {
>> 865 print "</programlisting></example>\n";
>> 866 } else {
>> 867 }
>> 868 print " </simplesect>\n";
>> 869 }
>> 870
>> 871 print "</sect2>\n\n";
564 } 872 }
565 873
566 ## 874 ##
567 # output function in man 875 # output function in man
568 sub output_function_man(%) { 876 sub output_function_man(%) {
569 my %args = %{$_[0]}; 877 my %args = %{$_[0]};
570 my ($parameter, $section); 878 my ($parameter, $section);
571 my $count; 879 my $count;
572 880
573 print ".TH \"$args{'function'}\" 9 \"$args !! 881 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"25 May 1998\" \"Kernel Hacker's Manual\" LINUX\n";
574 882
575 print ".SH NAME\n"; 883 print ".SH NAME\n";
576 print $args{'function'} . " \\- " . $args{ !! 884 print $args{'function'}." \\- ".$args{'purpose'}."\n";
577 885
578 print ".SH SYNOPSIS\n"; 886 print ".SH SYNOPSIS\n";
579 if ($args{'functiontype'} ne "") { !! 887 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
580 print ".B \"" . $args{'functiontype'} <<
581 } else { <<
582 print ".B \"" . $args{'function'} . "\ <<
583 } <<
584 $count = 0; 888 $count = 0;
585 my $parenth = "("; 889 my $parenth = "(";
586 my $post = ","; 890 my $post = ",";
587 foreach my $parameter (@{$args{'parameterl 891 foreach my $parameter (@{$args{'parameterlist'}}) {
588 if ($count == $#{$args{'parameterlist' !! 892 if ($count == $#{$args{'parameterlist'}}) {
589 $post = ");"; !! 893 $post = ");";
590 } !! 894 }
591 $type = $args{'parametertypes'}{$param !! 895 $type = $args{'parametertypes'}{$parameter};
592 if ($type =~ m/$function_pointer/) { !! 896 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
593 # pointer-to-function !! 897 # pointer-to-function
594 print ".BI \"" . $parenth . $1 . " !! 898 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
595 } else { !! 899 } else {
596 $type =~ s/([^\*])$/$1 /; !! 900 $type =~ s/([^\*])$/$1 /;
597 print ".BI \"" . $parenth . $type !! 901 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
598 } !! 902 }
599 $count++; !! 903 $count++;
600 $parenth = ""; !! 904 $parenth = "";
601 } 905 }
602 906
603 print ".SH ARGUMENTS\n"; 907 print ".SH ARGUMENTS\n";
604 foreach $parameter (@{$args{'parameterlist 908 foreach $parameter (@{$args{'parameterlist'}}) {
605 my $parameter_name = $parameter; !! 909 print ".IP \"".$parameter."\" 12\n";
606 $parameter_name =~ s/\[.*//; !! 910 output_highlight($args{'parameterdescs'}{$parameter});
607 <<
608 print ".IP \"" . $parameter . "\" 12\n <<
609 output_highlight($args{'parameterdescs <<
610 } 911 }
611 foreach $section (@{$args{'sectionlist'}}) 912 foreach $section (@{$args{'sectionlist'}}) {
612 print ".SH \"", uc $section, "\"\n"; !! 913 print ".SH \"", uc $section, "\"\n";
613 output_highlight($args{'sections'}{$se !! 914 output_highlight($args{'sections'}{$section});
614 } 915 }
615 } 916 }
616 917
617 ## 918 ##
618 # output enum in man 919 # output enum in man
619 sub output_enum_man(%) { 920 sub output_enum_man(%) {
620 my %args = %{$_[0]}; 921 my %args = %{$_[0]};
621 my ($parameter, $section); 922 my ($parameter, $section);
622 my $count; 923 my $count;
623 924
624 print ".TH \"$args{'module'}\" 9 \"enum $a 925 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
625 926
626 print ".SH NAME\n"; 927 print ".SH NAME\n";
627 print "enum " . $args{'enum'} . " \\- " . !! 928 print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
628 929
629 print ".SH SYNOPSIS\n"; 930 print ".SH SYNOPSIS\n";
630 print "enum " . $args{'enum'} . " {\n"; !! 931 print "enum ".$args{'enum'}." {\n";
631 $count = 0; 932 $count = 0;
632 foreach my $parameter (@{$args{'parameterl 933 foreach my $parameter (@{$args{'parameterlist'}}) {
633 print ".br\n.BI \" $parameter\"\n"; 934 print ".br\n.BI \" $parameter\"\n";
634 if ($count == $#{$args{'parameterlist' !! 935 if ($count == $#{$args{'parameterlist'}}) {
635 print "\n};\n"; !! 936 print "\n};\n";
636 last; !! 937 last;
637 } else { !! 938 }
638 print ", \n.br\n"; !! 939 else {
639 } !! 940 print ", \n.br\n";
640 $count++; !! 941 }
>> 942 $count++;
641 } 943 }
642 944
643 print ".SH Constants\n"; 945 print ".SH Constants\n";
644 foreach $parameter (@{$args{'parameterlist 946 foreach $parameter (@{$args{'parameterlist'}}) {
645 my $parameter_name = $parameter; !! 947 print ".IP \"".$parameter."\" 12\n";
646 $parameter_name =~ s/\[.*//; !! 948 output_highlight($args{'parameterdescs'}{$parameter});
647 <<
648 print ".IP \"" . $parameter . "\" 12\n <<
649 output_highlight($args{'parameterdescs <<
650 } 949 }
651 foreach $section (@{$args{'sectionlist'}}) 950 foreach $section (@{$args{'sectionlist'}}) {
652 print ".SH \"$section\"\n"; !! 951 print ".SH \"$section\"\n";
653 output_highlight($args{'sections'}{$se !! 952 output_highlight($args{'sections'}{$section});
654 } 953 }
655 } 954 }
656 955
657 ## 956 ##
658 # output struct in man 957 # output struct in man
659 sub output_struct_man(%) { 958 sub output_struct_man(%) {
660 my %args = %{$_[0]}; 959 my %args = %{$_[0]};
661 my ($parameter, $section); 960 my ($parameter, $section);
662 961
663 print ".TH \"$args{'module'}\" 9 \"" . $ar !! 962 print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
664 963
665 print ".SH NAME\n"; 964 print ".SH NAME\n";
666 print $args{'type'} . " " . $args{'struct' !! 965 print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
667 966
668 my $declaration = $args{'definition'}; <<
669 $declaration =~ s/\t/ /g; <<
670 $declaration =~ s/\n/"\n.br\n.BI \"/g; <<
671 print ".SH SYNOPSIS\n"; 967 print ".SH SYNOPSIS\n";
672 print $args{'type'} . " " . $args{'struct' !! 968 print $args{'type'}." ".$args{'struct'}." {\n";
673 print ".BI \"$declaration\n};\n.br\n\n"; <<
674 969
675 print ".SH Members\n"; !! 970 foreach my $parameter (@{$args{'parameterlist'}}) {
676 foreach $parameter (@{$args{'parameterlist !! 971 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
677 ($parameter =~ /^#/) && next; !! 972 print "\n.br\n";
678 !! 973 $type = $args{'parametertypes'}{$parameter};
679 my $parameter_name = $parameter; !! 974 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
680 $parameter_name =~ s/\[.*//; !! 975 # pointer-to-function
>> 976 print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
>> 977 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 978 print ".BI \" ".$1."\" ".$parameter.$2." \""."\"\n;\n";
>> 979 } else {
>> 980 $type =~ s/([^\*])$/$1 /;
>> 981 print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
>> 982 }
>> 983 print "\n.br\n";
>> 984 }
>> 985 print "};\n.br\n";
681 986
682 ($args{'parameterdescs'}{$parameter_na !! 987 print ".SH Arguments\n";
683 print ".IP \"" . $parameter . "\" 12\n !! 988 foreach $parameter (@{$args{'parameterlist'}}) {
684 output_highlight($args{'parameterdescs !! 989 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 990 print ".IP \"".$parameter."\" 12\n";
>> 991 output_highlight($args{'parameterdescs'}{$parameter});
685 } 992 }
686 foreach $section (@{$args{'sectionlist'}}) 993 foreach $section (@{$args{'sectionlist'}}) {
687 print ".SH \"$section\"\n"; !! 994 print ".SH \"$section\"\n";
688 output_highlight($args{'sections'}{$se !! 995 output_highlight($args{'sections'}{$section});
689 } 996 }
690 } 997 }
691 998
692 ## 999 ##
693 # output typedef in man 1000 # output typedef in man
694 sub output_typedef_man(%) { 1001 sub output_typedef_man(%) {
695 my %args = %{$_[0]}; 1002 my %args = %{$_[0]};
696 my ($parameter, $section); 1003 my ($parameter, $section);
697 1004
698 print ".TH \"$args{'module'}\" 9 \"$args{' 1005 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
699 1006
700 print ".SH NAME\n"; 1007 print ".SH NAME\n";
701 print "typedef " . $args{'typedef'} . " \\ !! 1008 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
702 1009
703 foreach $section (@{$args{'sectionlist'}}) 1010 foreach $section (@{$args{'sectionlist'}}) {
704 print ".SH \"$section\"\n"; !! 1011 print ".SH \"$section\"\n";
705 output_highlight($args{'sections'}{$se !! 1012 output_highlight($args{'sections'}{$section});
706 } 1013 }
707 } 1014 }
708 1015
709 sub output_blockhead_man(%) { !! 1016 sub output_intro_man(%) {
710 my %args = %{$_[0]}; 1017 my %args = %{$_[0]};
711 my ($parameter, $section); 1018 my ($parameter, $section);
712 my $count; 1019 my $count;
713 1020
714 print ".TH \"$args{'module'}\" 9 \"$args{' 1021 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
715 1022
716 foreach $section (@{$args{'sectionlist'}}) 1023 foreach $section (@{$args{'sectionlist'}}) {
717 print ".SH \"$section\"\n"; !! 1024 print ".SH \"$section\"\n";
718 output_highlight($args{'sections'}{$se !! 1025 output_highlight($args{'sections'}{$section});
719 } 1026 }
720 } 1027 }
721 1028
722 ## 1029 ##
723 # output in restructured text !! 1030 # output in text
724 # !! 1031 sub output_function_text(%) {
725 <<
726 # <<
727 # This could use some work; it's used to outpu <<
728 # starts by putting out the name of the doc se <<
729 # to duplicate a header already in the templat <<
730 # <<
731 sub output_blockhead_rst(%) { <<
732 my %args = %{$_[0]}; 1032 my %args = %{$_[0]};
733 my ($parameter, $section); 1033 my ($parameter, $section);
734 1034
735 foreach $section (@{$args{'sectionlist'}}) !! 1035 print "Function:\n\n";
736 next if (defined($nosymbol_table{$sect !! 1036 my $start=$args{'functiontype'}." ".$args{'function'}." (";
737 !! 1037 print $start;
738 if ($output_selection != OUTPUT_INCLUD <<
739 print ".. _$section:\n\n"; <<
740 print "**$section**\n\n"; <<
741 } <<
742 print_lineno($section_start_lines{$sec <<
743 output_highlight_rst($args{'sections'} <<
744 print "\n"; <<
745 } <<
746 } <<
747 <<
748 # <<
749 # Apply the RST highlights to a sub-block of t <<
750 # <<
751 sub highlight_block($) { <<
752 # The dohighlight kludge requires the text <<
753 my $contents = shift; <<
754 eval $dohighlight; <<
755 die $@ if $@; <<
756 return $contents; <<
757 } <<
758 <<
759 # <<
760 # Regexes used only here. <<
761 # <<
762 my $sphinx_literal = '^[^.].*::$'; <<
763 my $sphinx_cblock = '^\.\.\ +code-block::'; <<
764 <<
765 sub output_highlight_rst { <<
766 my $input = join "\n",@_; <<
767 my $output = ""; <<
768 my $line; <<
769 my $in_literal = 0; <<
770 my $litprefix; <<
771 my $block = ""; <<
772 <<
773 foreach $line (split "\n",$input) { <<
774 # <<
775 # If we're in a literal block, see if <<
776 # of it. Otherwise pass the line stra <<
777 # <<
778 if ($in_literal) { <<
779 if (! ($line =~ /^\s*$/)) { <<
780 # <<
781 # If this is the first non-bla <<
782 # block we need to figure out <<
783 # <<
784 if ($litprefix eq "") { <<
785 $line =~ /^(\s*)/; <<
786 $litprefix = '^' . $1; <<
787 $output .= $line . "\n"; <<
788 } elsif (! ($line =~ /$litpref <<
789 $in_literal = 0; <<
790 } else { <<
791 $output .= $line . "\n"; <<
792 } <<
793 } else { <<
794 $output .= $line . "\n"; <<
795 } <<
796 } <<
797 # <<
798 # Not in a literal block (or just drop <<
799 # <<
800 if (! $in_literal) { <<
801 $block .= $line . "\n"; <<
802 if (($line =~ /$sphinx_literal/) | <<
803 $in_literal = 1; <<
804 $litprefix = ""; <<
805 $output .= highlight_block($bl <<
806 $block = "" <<
807 } <<
808 } <<
809 } <<
810 <<
811 if ($block) { <<
812 $output .= highlight_block($block); <<
813 } <<
814 foreach $line (split "\n", $output) { <<
815 print $lineprefix . $line . "\n"; <<
816 } <<
817 } <<
818 <<
819 sub output_function_rst(%) { <<
820 my %args = %{$_[0]}; <<
821 my ($parameter, $section); <<
822 my $oldprefix = $lineprefix; <<
823 <<
824 my $signature = ""; <<
825 if ($args{'functiontype'} ne "") { <<
826 $signature = $args{'functiontype'} . " <<
827 } else { <<
828 $signature = $args{'function'} . " ("; <<
829 } <<
830 <<
831 my $count = 0; 1038 my $count = 0;
832 foreach my $parameter (@{$args{'parameterl 1039 foreach my $parameter (@{$args{'parameterlist'}}) {
833 if ($count ne 0) { !! 1040 $type = $args{'parametertypes'}{$parameter};
834 $signature .= ", "; !! 1041 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
835 } !! 1042 # pointer-to-function
836 $count++; !! 1043 print $1.$parameter.") (".$2;
837 $type = $args{'parametertypes'}{$param !! 1044 } else {
838 !! 1045 print $type." ".$parameter;
839 if ($type =~ m/$function_pointer/) { !! 1046 }
840 # pointer-to-function !! 1047 if ($count != $#{$args{'parameterlist'}}) {
841 $signature .= $1 . $parameter . ") !! 1048 $count++;
842 } else { !! 1049 print ",\n";
843 $signature .= $type; !! 1050 print " " x length($start);
844 } !! 1051 } else {
>> 1052 print ");\n\n";
>> 1053 }
845 } 1054 }
846 1055
847 $signature .= ")"; !! 1056 print "Arguments:\n\n";
848 <<
849 if ($sphinx_major < 3) { <<
850 if ($args{'typedef'}) { <<
851 print ".. c:type:: ". $args{'funct <<
852 print_lineno($declaration_start_li <<
853 print " **Typedef**: "; <<
854 $lineprefix = ""; <<
855 output_highlight_rst($args{'purpos <<
856 print "\n\n**Syntax**\n\n"; <<
857 print " ``$signature``\n\n"; <<
858 } else { <<
859 print ".. c:function:: $signature\ <<
860 } <<
861 } else { <<
862 if ($args{'typedef'} || $args{'functio <<
863 print ".. c:macro:: ". $args{'func <<
864 <<
865 if ($args{'typedef'}) { <<
866 print_lineno($declaration_star <<
867 print " **Typedef**: "; <<
868 $lineprefix = ""; <<
869 output_highlight_rst($args{'pu <<
870 print "\n\n**Syntax**\n\n"; <<
871 print " ``$signature``\n\n"; <<
872 } else { <<
873 print "``$signature``\n\n"; <<
874 } <<
875 } else { <<
876 print ".. c:function:: $signature\ <<
877 } <<
878 } <<
879 <<
880 if (!$args{'typedef'}) { <<
881 print_lineno($declaration_start_line); <<
882 $lineprefix = " "; <<
883 output_highlight_rst($args{'purpose'}) <<
884 print "\n"; <<
885 } <<
886 <<
887 # <<
888 # Put our descriptive text into a containe <<
889 # set the function prototypes apart. <<
890 # <<
891 print ".. container:: kernelindent\n\n"; <<
892 $lineprefix = " "; <<
893 print $lineprefix . "**Parameters**\n\n"; <<
894 foreach $parameter (@{$args{'parameterlist 1057 foreach $parameter (@{$args{'parameterlist'}}) {
895 my $parameter_name = $parameter; !! 1058 print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n";
896 $parameter_name =~ s/\[.*//; <<
897 $type = $args{'parametertypes'}{$param <<
898 <<
899 if ($type ne "") { <<
900 print $lineprefix . "``$type``\n"; <<
901 } else { <<
902 print $lineprefix . "``$parameter` <<
903 } <<
904 <<
905 print_lineno($parameterdesc_start_line <<
906 <<
907 $lineprefix = " "; <<
908 if (defined($args{'parameterdescs'}{$p <<
909 $args{'parameterdescs'}{$parameter <<
910 output_highlight_rst($args{'parame <<
911 } else { <<
912 print $lineprefix . "*undescribed* <<
913 } <<
914 $lineprefix = " "; <<
915 print "\n"; <<
916 } 1059 }
917 !! 1060 output_section_text(@_);
918 output_section_rst(@_); <<
919 $lineprefix = $oldprefix; <<
920 } 1061 }
921 1062
922 sub output_section_rst(%) { !! 1063 #output sections in text
>> 1064 sub output_section_text(%) {
923 my %args = %{$_[0]}; 1065 my %args = %{$_[0]};
924 my $section; 1066 my $section;
925 my $oldprefix = $lineprefix; <<
926 1067
927 foreach $section (@{$args{'sectionlist'}}) <<
928 print $lineprefix . "**$section**\n\n" <<
929 print_lineno($section_start_lines{$sec <<
930 output_highlight_rst($args{'sections'} <<
931 print "\n"; <<
932 } <<
933 print "\n"; 1068 print "\n";
>> 1069 foreach $section (@{$args{'sectionlist'}}) {
>> 1070 print "$section:\n\n";
>> 1071 output_highlight($args{'sections'}{$section});
>> 1072 }
>> 1073 print "\n\n";
934 } 1074 }
935 1075
936 sub output_enum_rst(%) { !! 1076 # output enum in text
>> 1077 sub output_enum_text(%) {
937 my %args = %{$_[0]}; 1078 my %args = %{$_[0]};
938 my ($parameter); 1079 my ($parameter);
939 my $oldprefix = $lineprefix; <<
940 my $count; 1080 my $count;
941 my $outer; !! 1081 print "Enum:\n\n";
942 1082
943 if ($sphinx_major < 3) { !! 1083 print "enum ".$args{'enum'}." {\n";
944 my $name = "enum " . $args{'enum'}; !! 1084 $count = 0;
945 print "\n\n.. c:type:: " . $name . "\n !! 1085 foreach $parameter (@{$args{'parameterlist'}}) {
946 } else { !! 1086 print "\t$parameter";
947 my $name = $args{'enum'}; !! 1087 if ($count != $#{$args{'parameterlist'}}) {
948 print "\n\n.. c:enum:: " . $name . "\n !! 1088 $count++;
>> 1089 print ",";
>> 1090 }
>> 1091 print "\n";
949 } 1092 }
950 print_lineno($declaration_start_line); !! 1093 print "};\n\n";
951 $lineprefix = " "; <<
952 output_highlight_rst($args{'purpose'}); <<
953 print "\n"; <<
954 1094
955 print ".. container:: kernelindent\n\n"; !! 1095 print "Constants:\n\n";
956 $outer = $lineprefix . " "; <<
957 $lineprefix = $outer . " "; <<
958 print $outer . "**Constants**\n\n"; <<
959 foreach $parameter (@{$args{'parameterlist 1096 foreach $parameter (@{$args{'parameterlist'}}) {
960 print $outer . "``$parameter``\n"; !! 1097 print "$parameter\n\t";
961 !! 1098 print $args{'parameterdescs'}{$parameter}."\n";
962 if ($args{'parameterdescs'}{$parameter <<
963 output_highlight_rst($args{'parame <<
964 } else { <<
965 print $lineprefix . "*undescribed* <<
966 } <<
967 print "\n"; <<
968 } 1099 }
969 print "\n"; !! 1100
970 $lineprefix = $oldprefix; !! 1101 output_section_text(@_);
971 output_section_rst(@_); <<
972 } 1102 }
973 1103
974 sub output_typedef_rst(%) { !! 1104 # output typedef in text
>> 1105 sub output_typedef_text(%) {
975 my %args = %{$_[0]}; 1106 my %args = %{$_[0]};
976 my ($parameter); 1107 my ($parameter);
977 my $oldprefix = $lineprefix; !! 1108 my $count;
978 my $name; !! 1109 print "Typedef:\n\n";
979 <<
980 if ($sphinx_major < 3) { <<
981 $name = "typedef " . $args{'typedef'}; <<
982 } else { <<
983 $name = $args{'typedef'}; <<
984 } <<
985 print "\n\n.. c:type:: " . $name . "\n\n"; <<
986 print_lineno($declaration_start_line); <<
987 $lineprefix = " "; <<
988 output_highlight_rst($args{'purpose'}); <<
989 print "\n"; <<
990 1110
991 $lineprefix = $oldprefix; !! 1111 print "typedef ".$args{'typedef'}."\n";
992 output_section_rst(@_); !! 1112 output_section_text(@_);
993 } 1113 }
994 1114
995 sub output_struct_rst(%) { !! 1115 # output struct as text
>> 1116 sub output_struct_text(%) {
996 my %args = %{$_[0]}; 1117 my %args = %{$_[0]};
997 my ($parameter); 1118 my ($parameter);
998 my $oldprefix = $lineprefix; <<
999 1119
1000 if ($sphinx_major < 3) { !! 1120 print $args{'type'}." ".$args{'struct'}.":\n\n";
1001 my $name = $args{'type'} . " " . $arg !! 1121 print $args{'type'}." ".$args{'struct'}." {\n";
1002 print "\n\n.. c:type:: " . $name . "\ !! 1122 foreach $parameter (@{$args{'parameterlist'}}) {
1003 } else { !! 1123 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1004 my $name = $args{'struct'}; !! 1124 $type = $args{'parametertypes'}{$parameter};
1005 if ($args{'type'} eq 'union') { !! 1125 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1006 print "\n\n.. c:union:: " . $name !! 1126 # pointer-to-function
1007 } else { !! 1127 print "\t$1 $parameter) ($2);\n";
1008 print "\n\n.. c:struct:: " . $nam !! 1128 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1009 } !! 1129 print "\t$1 $parameter$2;\n";
>> 1130 } else {
>> 1131 print "\t".$type." ".$parameter.";\n";
>> 1132 }
1010 } 1133 }
1011 print_lineno($declaration_start_line); !! 1134 print "};\n\n";
1012 $lineprefix = " "; <<
1013 output_highlight_rst($args{'purpose'}); <<
1014 print "\n"; <<
1015 <<
1016 print ".. container:: kernelindent\n\n"; <<
1017 print $lineprefix . "**Definition**::\n\n <<
1018 my $declaration = $args{'definition'}; <<
1019 $lineprefix = $lineprefix . " "; <<
1020 $declaration =~ s/\t/$lineprefix/g; <<
1021 print $lineprefix . $args{'type'} . " " . <<
1022 1135
1023 $lineprefix = " "; !! 1136 print "Members:\n\n";
1024 print $lineprefix . "**Members**\n\n"; <<
1025 foreach $parameter (@{$args{'parameterlis 1137 foreach $parameter (@{$args{'parameterlist'}}) {
1026 ($parameter =~ /^#/) && next; !! 1138 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1027 !! 1139 print "$parameter\n\t";
1028 my $parameter_name = $parameter; !! 1140 print $args{'parameterdescs'}{$parameter}."\n";
1029 $parameter_name =~ s/\[.*//; <<
1030 <<
1031 ($args{'parameterdescs'}{$parameter_n <<
1032 $type = $args{'parametertypes'}{$para <<
1033 print_lineno($parameterdesc_start_lin <<
1034 print $lineprefix . "``" . $parameter <<
1035 $lineprefix = " "; <<
1036 output_highlight_rst($args{'parameter <<
1037 $lineprefix = " "; <<
1038 print "\n"; <<
1039 } 1141 }
1040 print "\n"; 1142 print "\n";
1041 !! 1143 output_section_text(@_);
1042 $lineprefix = $oldprefix; <<
1043 output_section_rst(@_); <<
1044 } 1144 }
1045 1145
1046 ## none mode output functions !! 1146 sub output_intro_text(%) {
1047 !! 1147 my %args = %{$_[0]};
1048 sub output_function_none(%) { !! 1148 my ($parameter, $section);
1049 } <<
1050 <<
1051 sub output_enum_none(%) { <<
1052 } <<
1053 <<
1054 sub output_typedef_none(%) { <<
1055 } <<
1056 <<
1057 sub output_struct_none(%) { <<
1058 } <<
1059 1149
1060 sub output_blockhead_none(%) { !! 1150 foreach $section (@{$args{'sectionlist'}}) {
>> 1151 print " $section:\n";
>> 1152 print " -> ";
>> 1153 output_highlight($args{'sections'}{$section});
>> 1154 }
1061 } 1155 }
1062 1156
1063 ## 1157 ##
1064 # generic output function for all types (func !! 1158 # generic output function for typedefs
1065 # calls the generated, variable output_ funct <<
1066 # functype and output_mode <<
1067 sub output_declaration { 1159 sub output_declaration {
1068 no strict 'refs'; 1160 no strict 'refs';
1069 my $name = shift; 1161 my $name = shift;
1070 my $functype = shift; 1162 my $functype = shift;
1071 my $func = "output_${functype}_$output_mo 1163 my $func = "output_${functype}_$output_mode";
1072 !! 1164 if (($function_only==0) ||
1073 return if (defined($nosymbol_table{$name} !! 1165 ( $function_only == 1 && defined($function_table{$name})) ||
1074 !! 1166 ( $function_only == 2 && !defined($function_table{$name})))
1075 if (($output_selection == OUTPUT_ALL) || <<
1076 (($output_selection == OUTPUT_INCLUDE <<
1077 $output_selection == OUTPUT_EXPORTE <<
1078 defined($function_table{$name})) || <<
1079 ($output_selection == OUTPUT_INTERNAL <<
1080 !($functype eq "function" && defined <<
1081 { 1167 {
1082 &$func(@_); 1168 &$func(@_);
1083 $section_counter++; !! 1169 $section_counter++;
1084 } 1170 }
1085 } 1171 }
1086 1172
1087 ## 1173 ##
1088 # generic output function - calls the right o !! 1174 # generic output function - calls the right one based
1089 sub output_blockhead { !! 1175 # on current output mode.
>> 1176 sub output_intro {
1090 no strict 'refs'; 1177 no strict 'refs';
1091 my $func = "output_blockhead_" . $output_ !! 1178 my $func = "output_intro_".$output_mode;
1092 &$func(@_); 1179 &$func(@_);
1093 $section_counter++; 1180 $section_counter++;
1094 } 1181 }
1095 1182
1096 ## 1183 ##
1097 # takes a declaration (struct, union, enum, t !! 1184 # takes a declaration (struct, union, enum, typedef) and
1098 # invokes the right handler. NOT called for f 1185 # invokes the right handler. NOT called for functions.
1099 sub dump_declaration($$) { 1186 sub dump_declaration($$) {
1100 no strict 'refs'; 1187 no strict 'refs';
1101 my ($prototype, $file) = @_; 1188 my ($prototype, $file) = @_;
1102 my $func = "dump_" . $decl_type; !! 1189 my $func = "dump_".$decl_type;
1103 &$func(@_); 1190 &$func(@_);
1104 } 1191 }
1105 1192
1106 sub dump_union($$) { 1193 sub dump_union($$) {
1107 dump_struct(@_); 1194 dump_struct(@_);
1108 } 1195 }
1109 1196
1110 sub dump_struct($$) { 1197 sub dump_struct($$) {
1111 my $x = shift; 1198 my $x = shift;
1112 my $file = shift; 1199 my $file = shift;
1113 my $decl_type; <<
1114 my $members; <<
1115 my $type = qr{struct|union}; <<
1116 # For capturing struct/union definition b <<
1117 my $qualifiers = qr{$attribute|__packed|_ <<
1118 my $definition_body = qr{\{(.*)\}\s*$qual <<
1119 my $struct_members = qr{($type)([^\{\};]+ <<
1120 1200
1121 if ($x =~ /($type)\s+(\w+)\s*$definition_ !! 1201 if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1122 $decl_type = $1; <<
1123 $declaration_name = $2; 1202 $declaration_name = $2;
1124 $members = $3; !! 1203 my $members = $3;
1125 } elsif ($x =~ /typedef\s+($type)\s*$defi <<
1126 $decl_type = $1; <<
1127 $declaration_name = $3; <<
1128 $members = $2; <<
1129 } <<
1130 <<
1131 if ($members) { <<
1132 if ($identifier ne $declaration_name) <<
1133 emit_warning("${file}:$.", "expec <<
1134 return; <<
1135 } <<
1136 <<
1137 # ignore members marked private: <<
1138 $members =~ s/\/\*\s*private:.*?\/\*\ <<
1139 $members =~ s/\/\*\s*private:.*//gosi <<
1140 # strip comments: <<
1141 $members =~ s/\/\*.*?\*\///gos; <<
1142 # strip attributes <<
1143 $members =~ s/\s*$attribute/ /gi; <<
1144 $members =~ s/\s*__aligned\s*\([^;]*\ <<
1145 $members =~ s/\s*__counted_by\s*\([^; <<
1146 $members =~ s/\s*__counted_by_(le|be) <<
1147 $members =~ s/\s*__packed\s*/ /gos; <<
1148 $members =~ s/\s*CRYPTO_MINALIGN_ATTR <<
1149 $members =~ s/\s*____cacheline_aligne <<
1150 $members =~ s/\s*____cacheline_aligne <<
1151 # unwrap struct_group(): <<
1152 # - first eat non-declaration paramet <<
1153 # - then remove macro, outer parens, <<
1154 $members =~ s/\bstruct_group\s*\(([^, <<
1155 $members =~ s/\bstruct_group_attr\s*\ <<
1156 $members =~ s/\bstruct_group_tagged\s <<
1157 $members =~ s/\b__struct_group\s*\(([ <<
1158 $members =~ s/\bSTRUCT_GROUP(\(((?:(? <<
1159 <<
1160 my $args = qr{([^,)]+)}; <<
1161 # replace DECLARE_BITMAP <<
1162 $members =~ s/__ETHTOOL_DECLARE_LINK_ <<
1163 $members =~ s/DECLARE_PHY_INTERFACE_M <<
1164 $members =~ s/DECLARE_BITMAP\s*\($arg <<
1165 # replace DECLARE_HASHTABLE <<
1166 $members =~ s/DECLARE_HASHTABLE\s*\($ <<
1167 # replace DECLARE_KFIFO <<
1168 $members =~ s/DECLARE_KFIFO\s*\($args <<
1169 # replace DECLARE_KFIFO_PTR <<
1170 $members =~ s/DECLARE_KFIFO_PTR\s*\($ <<
1171 # replace DECLARE_FLEX_ARRAY <<
1172 $members =~ s/(?:__)?DECLARE_FLEX_ARR <<
1173 #replace DEFINE_DMA_UNMAP_ADDR <<
1174 $members =~ s/DEFINE_DMA_UNMAP_ADDR\s <<
1175 #replace DEFINE_DMA_UNMAP_LEN <<
1176 $members =~ s/DEFINE_DMA_UNMAP_LEN\s* <<
1177 my $declaration = $members; <<
1178 <<
1179 # Split nested struct/union elements <<
1180 while ($members =~ m/$struct_members/ <<
1181 my $newmember; <<
1182 my $maintype = $1; <<
1183 my $ids = $4; <<
1184 my $content = $3; <<
1185 foreach my $id(split /,/, $ids) { <<
1186 $newmember .= "$maintype $id; <<
1187 <<
1188 $id =~ s/[:\[].*//; <<
1189 $id =~ s/^\s*\**(\S+)\s*/$1/; <<
1190 foreach my $arg (split /;/, $ <<
1191 next if ($arg =~ m/^\s*$/ <<
1192 if ($arg =~ m/^([^\(]+\(\ <<
1193 # pointer-to-function <<
1194 my $type = $1; <<
1195 my $name = $2; <<
1196 my $extra = $3; <<
1197 next if (!$name); <<
1198 if ($id =~ m/^\s*$/) <<
1199 # anonymous struc <<
1200 $newmember .= "$t <<
1201 } else { <<
1202 $newmember .= "$t <<
1203 } <<
1204 } else { <<
1205 my $type; <<
1206 my $names; <<
1207 $arg =~ s/^\s+//; <<
1208 $arg =~ s/\s+$//; <<
1209 # Handle bitmaps <<
1210 $arg =~ s/:\s*\d+\s*/ <<
1211 # Handle arrays <<
1212 $arg =~ s/\[.*\]//g; <<
1213 # The type may have m <<
1214 # and multiple IDs ca <<
1215 # const struct foo <<
1216 # So, we remove space <<
1217 # names, in order to <<
1218 # and commas for the <<
1219 $arg =~ s/\s*,\s*/,/g <<
1220 if ($arg =~ m/(.*)\s+ <<
1221 $type = $1; <<
1222 $names = $2; <<
1223 } else { <<
1224 $newmember .= "$a <<
1225 next; <<
1226 } <<
1227 foreach my $name (spl <<
1228 $name =~ s/^\s*\* <<
1229 next if (($name = <<
1230 if ($id =~ m/^\s* <<
1231 # anonymous s <<
1232 $newmember .= <<
1233 } else { <<
1234 $newmember .= <<
1235 } <<
1236 } <<
1237 } <<
1238 } <<
1239 } <<
1240 $members =~ s/$struct_members/$ne <<
1241 } <<
1242 <<
1243 # Ignore other nested elements, like <<
1244 $members =~ s/(\{[^\{\}]*\})//g; <<
1245 <<
1246 create_parameterlist($members, ';', $ <<
1247 check_sections($file, $declaration_na <<
1248 <<
1249 # Adjust declaration for better displ <<
1250 $declaration =~ s/([\{;])/$1\n/g; <<
1251 $declaration =~ s/\}\s+;/};/g; <<
1252 # Better handle inlined enums <<
1253 do {} while ($declaration =~ s/(enum\ <<
1254 <<
1255 my @def_args = split /\n/, $declarati <<
1256 my $level = 1; <<
1257 $declaration = ""; <<
1258 foreach my $clause (@def_args) { <<
1259 $clause =~ s/^\s+//; <<
1260 $clause =~ s/\s+$//; <<
1261 $clause =~ s/\s+/ /; <<
1262 next if (!$clause); <<
1263 $level-- if ($clause =~ m/(\})/ & <<
1264 if (!($clause =~ m/^\s*#/)) { <<
1265 $declaration .= "\t" x $level <<
1266 } <<
1267 $declaration .= "\t" . $clause . <<
1268 $level++ if ($clause =~ m/(\{)/ & <<
1269 } <<
1270 output_declaration($declaration_name, <<
1271 'struct', <<
1272 {'struct' => $declaration_ <<
1273 'module' => $modulename, <<
1274 'definition' => $declarat <<
1275 'parameterlist' => \@para <<
1276 'parameterdescs' => \%par <<
1277 'parametertypes' => \%par <<
1278 'sectionlist' => \@sectio <<
1279 'sections' => \%sections, <<
1280 'purpose' => $declaration <<
1281 'type' => $decl_type <<
1282 }); <<
1283 } else { <<
1284 print STDERR "${file}:$.: error: Cann <<
1285 ++$errors; <<
1286 } <<
1287 } <<
1288 <<
1289 <<
1290 sub show_warnings($$) { <<
1291 my $functype = shift; <<
1292 my $name = shift; <<
1293 1204
1294 return 0 if (defined($nosymbol_table{$nam !! 1205 # ignore embedded structs or unions
>> 1206 $members =~ s/{.*}//g;
1295 1207
1296 return 1 if ($output_selection == OUTPUT_ !! 1208 create_parameterlist($members, ';', $file);
1297 1209
1298 if ($output_selection == OUTPUT_EXPORTED) !! 1210 output_declaration($declaration_name,
1299 if (defined($function_table{$name})) !! 1211 'struct',
1300 return 1; !! 1212 {'struct' => $declaration_name,
1301 } else { !! 1213 'module' => $modulename,
1302 return 0; !! 1214 'parameterlist' => \@parameterlist,
1303 } !! 1215 'parameterdescs' => \%parameterdescs,
1304 } !! 1216 'parametertypes' => \%parametertypes,
1305 if ($output_selection == OUTPUT_INTERNAL) !! 1217 'sectionlist' => \@sectionlist,
1306 if (!($functype eq "function" && defi !! 1218 'sections' => \%sections,
1307 return 1; !! 1219 'purpose' => $declaration_purpose,
1308 } else { !! 1220 'type' => $decl_type
1309 return 0; !! 1221 });
1310 } !! 1222 }
>> 1223 else {
>> 1224 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
>> 1225 ++$errors;
1311 } 1226 }
1312 if ($output_selection == OUTPUT_INCLUDE) <<
1313 if (defined($function_table{$name})) <<
1314 return 1; <<
1315 } else { <<
1316 return 0; <<
1317 } <<
1318 } <<
1319 die("Please add the new output type at sh <<
1320 } 1227 }
1321 1228
1322 sub dump_enum($$) { 1229 sub dump_enum($$) {
1323 my $x = shift; 1230 my $x = shift;
1324 my $file = shift; 1231 my $file = shift;
1325 my $members; <<
1326 <<
1327 # ignore members marked private: <<
1328 $x =~ s/\/\*\s*private:.*?\/\*\s*public:. <<
1329 $x =~ s/\/\*\s*private:.*}/}/gosi; <<
1330 <<
1331 $x =~ s@/\*.*?\*/@@gos; # strip comme <<
1332 # strip #define macros inside enums <<
1333 $x =~ s@#\s*((define|ifdef|if)\s+|endif)[ <<
1334 1232
1335 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\ !! 1233 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1336 $declaration_name = $2; <<
1337 $members = $1; <<
1338 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) <<
1339 $declaration_name = $1; 1234 $declaration_name = $1;
1340 $members = $2; !! 1235 my $members = $2;
1341 } <<
1342 <<
1343 if ($members) { <<
1344 if ($identifier ne $declaration_name) <<
1345 if ($identifier eq "") { <<
1346 emit_warning("${file}:$.", "w <<
1347 } else { <<
1348 emit_warning("${file}:$.", "e <<
1349 } <<
1350 return; <<
1351 } <<
1352 $declaration_name = "(anonymous)" if <<
1353 1236
1354 my %_members; !! 1237 foreach my $arg (split ',', $members) {
1355 !! 1238 $arg =~ s/^\s*(\w+).*/$1/;
1356 $members =~ s/\s+$//; !! 1239 push @parameterlist, $arg;
1357 $members =~ s/\([^;]*?[\)]//g; !! 1240 if (!$parameterdescs{$arg}) {
1358 !! 1241 $parameterdescs{$arg} = $undescribed;
1359 foreach my $arg (split ',', $members) !! 1242 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1360 $arg =~ s/^\s*(\w+).*/$1/; !! 1243 "not described in enum '$declaration_name'\n";
1361 push @parameterlist, $arg; !! 1244 }
1362 if (!$parameterdescs{$arg}) { !! 1245
1363 $parameterdescs{$arg} = $unde !! 1246 }
1364 if (show_warnings("enum", $de !! 1247
1365 emit_warning("${file}:$." !! 1248 output_declaration($declaration_name,
1366 } !! 1249 'enum',
1367 } !! 1250 {'enum' => $declaration_name,
1368 $_members{$arg} = 1; !! 1251 'module' => $modulename,
1369 } !! 1252 'parameterlist' => \@parameterlist,
1370 !! 1253 'parameterdescs' => \%parameterdescs,
1371 while (my ($k, $v) = each %parameterd !! 1254 'sectionlist' => \@sectionlist,
1372 if (!exists($_members{$k})) { !! 1255 'sections' => \%sections,
1373 if (show_warnings("enum", $de !! 1256 'purpose' => $declaration_purpose
1374 emit_warning("${file}:$." !! 1257 });
1375 } !! 1258 }
1376 } !! 1259 else {
1377 } !! 1260 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1378 !! 1261 ++$errors;
1379 output_declaration($declaration_name, <<
1380 'enum', <<
1381 {'enum' => $declar <<
1382 'module' => $modu <<
1383 'parameterlist' = <<
1384 'parameterdescs' <<
1385 'sectionlist' => <<
1386 'sections' => \%s <<
1387 'purpose' => $dec <<
1388 }); <<
1389 } else { <<
1390 print STDERR "${file}:$.: error: Cann <<
1391 ++$errors; <<
1392 } 1262 }
1393 } 1263 }
1394 1264
1395 my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8 <<
1396 my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; <<
1397 my $typedef_args = qr { \s*\((.*)\); }x; <<
1398 <<
1399 my $typedef1 = qr { typedef$typedef_type\($ty <<
1400 my $typedef2 = qr { typedef$typedef_type$type <<
1401 <<
1402 sub dump_typedef($$) { 1265 sub dump_typedef($$) {
1403 my $x = shift; 1266 my $x = shift;
1404 my $file = shift; 1267 my $file = shift;
1405 1268
1406 $x =~ s@/\*.*?\*/@@gos; # strip comme <<
1407 <<
1408 # Parse function typedef prototypes <<
1409 if ($x =~ $typedef1 || $x =~ $typedef2) { <<
1410 $return_type = $1; <<
1411 $declaration_name = $2; <<
1412 my $args = $3; <<
1413 $return_type =~ s/^\s+//; <<
1414 <<
1415 if ($identifier ne $declaration_name) <<
1416 emit_warning("${file}:$.", "expec <<
1417 return; <<
1418 } <<
1419 <<
1420 create_parameterlist($args, ',', $fil <<
1421 <<
1422 output_declaration($declaration_name, <<
1423 'function', <<
1424 {'function' => $de <<
1425 'typedef' => 1, <<
1426 'module' => $modu <<
1427 'functiontype' => <<
1428 'parameterlist' = <<
1429 'parameterdescs' <<
1430 'parametertypes' <<
1431 'sectionlist' => <<
1432 'sections' => \%s <<
1433 'purpose' => $dec <<
1434 }); <<
1435 return; <<
1436 } <<
1437 <<
1438 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\ 1269 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1439 $x =~ s/\(*.\)\s*;$/;/; 1270 $x =~ s/\(*.\)\s*;$/;/;
1440 $x =~ s/\[*.\]\s*;$/;/; !! 1271 $x =~ s/\[*.\]\s*;$/;/;
1441 } 1272 }
1442 1273
1443 if ($x =~ /typedef.*\s+(\w+)\s*;/) { 1274 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1444 $declaration_name = $1; 1275 $declaration_name = $1;
1445 1276
1446 if ($identifier ne $declaration_name) !! 1277 output_declaration($declaration_name,
1447 emit_warning("${file}:$.", "expec !! 1278 'typedef',
1448 return; !! 1279 {'typedef' => $declaration_name,
1449 } !! 1280 'module' => $modulename,
1450 !! 1281 'sectionlist' => \@sectionlist,
1451 output_declaration($declaration_name, !! 1282 'sections' => \%sections,
1452 'typedef', !! 1283 'purpose' => $declaration_purpose
1453 {'typedef' => $dec !! 1284 });
1454 'module' => $modu !! 1285 }
1455 'sectionlist' => !! 1286 else {
1456 'sections' => \%s !! 1287 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1457 'purpose' => $dec !! 1288 ++$errors;
1458 }); <<
1459 } else { <<
1460 print STDERR "${file}:$.: error: Cann <<
1461 ++$errors; <<
1462 } 1289 }
1463 } 1290 }
1464 1291
1465 sub save_struct_actual($) { !! 1292 sub create_parameterlist($$$) {
1466 my $actual = shift; <<
1467 <<
1468 # strip all spaces from the actual param <<
1469 $actual =~ s/\s*//g; <<
1470 $struct_actual = $struct_actual . $actual <<
1471 } <<
1472 <<
1473 sub create_parameterlist($$$$) { <<
1474 my $args = shift; 1293 my $args = shift;
1475 my $splitter = shift; 1294 my $splitter = shift;
1476 my $file = shift; 1295 my $file = shift;
1477 my $declaration_name = shift; <<
1478 my $type; 1296 my $type;
1479 my $param; 1297 my $param;
1480 1298
1481 # temporarily replace commas inside funct !! 1299 while ($args =~ /(\([^\),]+),/) {
1482 my $arg_expr = qr{\([^\),]+}; !! 1300 $args =~ s/(\([^\),]+),/$1#/g;
1483 while ($args =~ /$arg_expr,/) { <<
1484 $args =~ s/($arg_expr),/$1#/g; <<
1485 } 1301 }
1486 !! 1302
1487 foreach my $arg (split($splitter, $args)) 1303 foreach my $arg (split($splitter, $args)) {
1488 # strip comments <<
1489 $arg =~ s/\/\*.*\*\///; <<
1490 # ignore argument attributes <<
1491 $arg =~ s/\sPOS0?\s/ /; <<
1492 # strip leading/trailing spaces 1304 # strip leading/trailing spaces
1493 $arg =~ s/^\s*//; 1305 $arg =~ s/^\s*//;
1494 $arg =~ s/\s*$//; !! 1306 $arg =~ s/\s*$//;
1495 $arg =~ s/\s+/ /; !! 1307 $arg =~ s/\s+/ /;
1496 <<
1497 if ($arg =~ /^#/) { <<
1498 # Treat preprocessor directive as <<
1499 # corresponding data structures " <<
1500 # output_* subs. <<
1501 push_parameter($arg, "", "", $fil <<
1502 } elsif ($arg =~ m/\(.+\)\s*\(/) { <<
1503 # pointer-to-function <<
1504 $arg =~ tr/#/,/; <<
1505 $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\ <<
1506 $param = $1; <<
1507 $type = $arg; <<
1508 $type =~ s/([^\(]+\(\*?)\s*$param <<
1509 save_struct_actual($param); <<
1510 push_parameter($param, $type, $ar <<
1511 } elsif ($arg =~ m/\(.+\)\s*\[/) { <<
1512 # array-of-pointers <<
1513 $arg =~ tr/#/,/; <<
1514 $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\ <<
1515 $param = $1; <<
1516 $type = $arg; <<
1517 $type =~ s/([^\(]+\(\*?)\s*$param <<
1518 save_struct_actual($param); <<
1519 push_parameter($param, $type, $ar <<
1520 } elsif ($arg) { <<
1521 $arg =~ s/\s*:\s*/:/g; <<
1522 $arg =~ s/\s*\[/\[/g; <<
1523 <<
1524 my @args = split('\s*,\s*', $arg) <<
1525 if ($args[0] =~ m/\*/) { <<
1526 $args[0] =~ s/(\*+)\s*/ $1/; <<
1527 } <<
1528 <<
1529 my @first_arg; <<
1530 if ($args[0] =~ /^(.*\s+)(.*?\[.* <<
1531 shift @args; <<
1532 push(@first_arg, split('\s+', <<
1533 push(@first_arg, $2); <<
1534 } else { <<
1535 @first_arg = split('\s+', shi <<
1536 } <<
1537 1308
1538 unshift(@args, pop @first_arg); !! 1309 if ($arg =~ m/\(/) {
1539 $type = join " ", @first_arg; !! 1310 # pointer-to-function
1540 !! 1311 $arg =~ tr/#/,/;
1541 foreach $param (@args) { !! 1312 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
1542 if ($param =~ m/^(\*+)\s*(.*) !! 1313 $param = $1;
1543 save_struct_actual($2); !! 1314 $type = $arg;
1544 !! 1315 $type =~ s/([^\(]+\(\*)$param/$1/;
1545 push_parameter($2, "$type !! 1316 } else {
1546 } elsif ($param =~ m/(.*?):(\ !! 1317 # evil magic to get fixed array parameters to work
1547 if ($type ne "") { # skip !! 1318 $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/;
1548 save_struct_actual($1 !! 1319 my @args = split('\s', $arg);
1549 push_parameter($1, "$ !! 1320
1550 } !! 1321 $param = pop @args;
1551 } else { !! 1322 if ($param =~ m/^(\*+)(.*)/) {
1552 save_struct_actual($param !! 1323 $param = $2;
1553 push_parameter($param, $t !! 1324 push @args, $1;
1554 } !! 1325 }
1555 } !! 1326 elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) {
>> 1327 $param = $1;
>> 1328 push @args, ":$2";
>> 1329 }
>> 1330 $type = join " ", @args;
>> 1331 }
>> 1332
>> 1333 if ($type eq "" && $param eq "...")
>> 1334 {
>> 1335 $type="...";
>> 1336 $param="...";
>> 1337 $parameterdescs{"..."} = "variable arguments";
>> 1338 }
>> 1339 elsif ($type eq "" && ($param eq "" or $param eq "void"))
>> 1340 {
>> 1341 $type="";
>> 1342 $param="void";
>> 1343 $parameterdescs{void} = "no arguments";
>> 1344 }
>> 1345 if (defined $type && $type && !defined $parameterdescs{$param}) {
>> 1346 $parameterdescs{$param} = $undescribed;
>> 1347
>> 1348 if (($type eq 'function') || ($type eq 'enum')) {
>> 1349 print STDERR "Warning(${file}:$.): Function parameter ".
>> 1350 "or member '$param' not " .
>> 1351 "described in '$declaration_name'\n";
>> 1352 }
>> 1353 ++$errors;
1556 } 1354 }
1557 } <<
1558 } <<
1559 1355
1560 sub push_parameter($$$$$) { !! 1356 push @parameterlist, $param;
1561 my $param = shift; !! 1357 $parametertypes{$param} = $type;
1562 my $type = shift; <<
1563 my $org_arg = shift; <<
1564 my $file = shift; <<
1565 my $declaration_name = shift; <<
1566 <<
1567 if (($anon_struct_union == 1) && ($type e <<
1568 ($param eq "}")) { <<
1569 return; # ignore the ending }; <<
1570 } <<
1571 <<
1572 $anon_struct_union = 0; <<
1573 $param =~ s/[\[\)].*//; <<
1574 <<
1575 if ($type eq "" && $param =~ /\.\.\.$/) <<
1576 { <<
1577 if (!$param =~ /\w\.\.\.$/) { <<
1578 # handles unnamed variable parame <<
1579 $param = "..."; <<
1580 } elsif ($param =~ /\w\.\.\.$/) { <<
1581 # for named variable parameters o <<
1582 $param =~ s/\.\.\.$//; <<
1583 } <<
1584 if (!defined $parameterdescs{$param} <<
1585 $parameterdescs{$param} = "variab <<
1586 } <<
1587 } <<
1588 elsif ($type eq "" && ($param eq "" or $p <<
1589 { <<
1590 $param="void"; <<
1591 $parameterdescs{void} = "no arguments <<
1592 } <<
1593 elsif ($type eq "" && ($param eq "struct" <<
1594 # handle unnamed (anonymous) union or str <<
1595 { <<
1596 $type = $param; <<
1597 $param = "{unnamed_" . $param . "}"; <<
1598 $parameterdescs{$param} = "anonymous\ <<
1599 $anon_struct_union = 1; <<
1600 } <<
1601 elsif ($param =~ "__cacheline_group" ) <<
1602 # handle cache group enforcing variables: <<
1603 { <<
1604 return; # ignore __cacheline_group_be <<
1605 } <<
1606 <<
1607 # warn if parameter has no description <<
1608 # (but ignore ones starting with # as the <<
1609 # but inline preprocessor statements); <<
1610 # Note: It will also ignore void params a <<
1611 if (!defined $parameterdescs{$param} && $ <<
1612 $parameterdescs{$param} = $undescribe <<
1613 <<
1614 if (show_warnings($type, $declaration <<
1615 emit_warning("${file}:$.", "Funct <<
1616 } <<
1617 } <<
1618 <<
1619 # strip spaces from $param so that it is <<
1620 # on @parameterlist; <<
1621 # this fixes a problem where check_sectio <<
1622 # a parameter like "addr[6 + 2]" because <<
1623 # as "addr[6", "+", "2]" on the parameter <<
1624 # but it's better to maintain the param s <<
1625 # so just weaken the string compare in ch <<
1626 # "[blah" in a parameter string; <<
1627 ###$param =~ s/\s*//g; <<
1628 push @parameterlist, $param; <<
1629 $org_arg =~ s/\s\s+/ /g; <<
1630 $parametertypes{$param} = $org_arg; <<
1631 } <<
1632 <<
1633 sub check_sections($$$$$) { <<
1634 my ($file, $decl_name, $decl_type, $sectc <<
1635 my @sects = split ' ', $sectcheck; <<
1636 my @prms = split ' ', $prmscheck; <<
1637 my $err; <<
1638 my ($px, $sx); <<
1639 my $prm_clean; # strip trailing "[ <<
1640 <<
1641 foreach $sx (0 .. $#sects) { <<
1642 $err = 1; <<
1643 foreach $px (0 .. $#prms) { <<
1644 $prm_clean = $prms[$px]; <<
1645 $prm_clean =~ s/\[.*\]//; <<
1646 $prm_clean =~ s/$attribute//i; <<
1647 # ignore array size in a paramete <<
1648 # however, the original param str <<
1649 # spaces, e.g.: addr[6 + 2] <<
1650 # and this appears in @prms as "a <<
1651 # parameter list is split at spac <<
1652 # hence just ignore "[..." for th <<
1653 $prm_clean =~ s/\[.*//; <<
1654 <<
1655 ##$prm_clean =~ s/^\**//; <<
1656 if ($prm_clean eq $sects[$sx]) { <<
1657 $err = 0; <<
1658 last; <<
1659 } <<
1660 } <<
1661 if ($err) { <<
1662 if ($decl_type eq "function") { <<
1663 emit_warning("${file}:$.", <<
1664 "Excess function paramete <<
1665 "'$sects[$sx]' " . <<
1666 "description in '$decl_na <<
1667 } elsif (($decl_type eq "struct") <<
1668 ($decl_type eq "uni <<
1669 emit_warning("${file}:$.", <<
1670 "Excess $decl_type member <<
1671 "'$sects[$sx]' " . <<
1672 "description in '$decl_na <<
1673 } <<
1674 } <<
1675 } <<
1676 } <<
1677 <<
1678 ## <<
1679 # Checks the section describing the return va <<
1680 sub check_return_section { <<
1681 my $file = shift; <<
1682 my $declaration_name = shift; <<
1683 my $return_type = shift; <<
1684 <<
1685 # Ignore an empty return type (It's a mac <<
1686 # Ignore functions with a "void" return t <<
1687 if (($return_type eq "") || ($return_type <<
1688 return; <<
1689 } <<
1690 <<
1691 if (!defined($sections{$section_return}) <<
1692 $sections{$section_return} eq "") <<
1693 { <<
1694 emit_warning("${file}:$.", <<
1695 "No description found fo <<
1696 "'$declaration_name'\n") <<
1697 } 1358 }
1698 } 1359 }
1699 1360
1700 ## 1361 ##
1701 # takes a function prototype and the name of 1362 # takes a function prototype and the name of the current file being
1702 # processed and spits out all the details sto 1363 # processed and spits out all the details stored in the global
1703 # arrays/hashes. 1364 # arrays/hashes.
1704 sub dump_function($$) { 1365 sub dump_function($$) {
1705 my $prototype = shift; 1366 my $prototype = shift;
1706 my $file = shift; 1367 my $file = shift;
1707 my $noret = 0; <<
1708 <<
1709 print_lineno($new_start_line); <<
1710 1368
1711 $prototype =~ s/^static +//; 1369 $prototype =~ s/^static +//;
1712 $prototype =~ s/^extern +//; 1370 $prototype =~ s/^extern +//;
1713 $prototype =~ s/^asmlinkage +//; <<
1714 $prototype =~ s/^inline +//; 1371 $prototype =~ s/^inline +//;
1715 $prototype =~ s/^__inline__ +//; 1372 $prototype =~ s/^__inline__ +//;
1716 $prototype =~ s/^__inline +//; !! 1373 $prototype =~ s/^#define +//; #ak added
1717 $prototype =~ s/^__always_inline +//; <<
1718 $prototype =~ s/^noinline +//; <<
1719 $prototype =~ s/^__FORTIFY_INLINE +//; <<
1720 $prototype =~ s/__init +//; <<
1721 $prototype =~ s/__init_or_module +//; <<
1722 $prototype =~ s/__deprecated +//; <<
1723 $prototype =~ s/__flatten +//; <<
1724 $prototype =~ s/__meminit +//; <<
1725 $prototype =~ s/__must_check +//; <<
1726 $prototype =~ s/__weak +//; <<
1727 $prototype =~ s/__sched +//; <<
1728 $prototype =~ s/_noprof//; <<
1729 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s <<
1730 $prototype =~ s/__(?:re)?alloc_size\s*\(\ <<
1731 $prototype =~ s/__diagnose_as\s*\(\s*\S+\ <<
1732 $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s <<
1733 my $define = $prototype =~ s/^#\s*define\ <<
1734 $prototype =~ s/__attribute_const__ +//; <<
1735 $prototype =~ s/__attribute__\s*\(\( <<
1736 (?: <<
1737 [\w\s]++ # attribut <<
1738 (?:\([^)]*+\))? # attribut <<
1739 \s*+,? # optional <<
1740 )+ <<
1741 \)\)\s+//x; <<
1742 1374
1743 # Yes, this truly is vile. We are lookin 1375 # Yes, this truly is vile. We are looking for:
1744 # 1. Return type (may be nothing if we're 1376 # 1. Return type (may be nothing if we're looking at a macro)
1745 # 2. Function name 1377 # 2. Function name
1746 # 3. Function parameters. 1378 # 3. Function parameters.
1747 # 1379 #
1748 # All the while we have to watch out for 1380 # All the while we have to watch out for function pointer parameters
1749 # (which IIRC is what the two sections ar 1381 # (which IIRC is what the two sections are for), C types (these
1750 # regexps don't even start to express all 1382 # regexps don't even start to express all the possibilities), and
1751 # so on. 1383 # so on.
1752 # 1384 #
1753 # If you mess with these regexps, it's a 1385 # If you mess with these regexps, it's a good idea to check that
1754 # the following functions' documentation 1386 # the following functions' documentation still comes out right:
1755 # - parport_register_device (function poi 1387 # - parport_register_device (function pointer parameters)
1756 # - atomic_set (macro) 1388 # - atomic_set (macro)
1757 # - pci_match_device, __copy_to_user (lon !! 1389 # - pci_match_device (long return type)
1758 my $name = qr{[a-zA-Z0-9_~:]+}; <<
1759 my $prototype_end1 = qr{[^\(]*}; <<
1760 my $prototype_end2 = qr{[^\{]*}; <<
1761 my $prototype_end = qr{\(($prototype_end1 <<
1762 my $type1 = qr{[\w\s]+}; <<
1763 my $type2 = qr{$type1\*+}; <<
1764 <<
1765 if ($define && $prototype =~ m/^()($name) <<
1766 # This is an object-like macro, it ha <<
1767 # list. <<
1768 # Function-like macros are not allowe <<
1769 # declaration_name and opening parent <<
1770 $return_type = $1; <<
1771 $declaration_name = $2; <<
1772 $noret = 1; <<
1773 } elsif ($prototype =~ m/^()($name)\s*$pr <<
1774 $prototype =~ m/^($type1)\s+($name)\s <<
1775 $prototype =~ m/^($type2+)\s*($name)\ <<
1776 $return_type = $1; <<
1777 $declaration_name = $2; <<
1778 my $args = $3; <<
1779 1390
1780 create_parameterlist($args, ',', $fil !! 1391 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1781 } else { !! 1392 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1782 emit_warning("${file}:$.", "cannot un !! 1393 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1783 return; !! 1394 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1784 } !! 1395 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1396 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1397 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1398 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1399 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1400 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1401 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1402 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1403 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1404 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
>> 1405 $return_type = $1;
>> 1406 $declaration_name = $2;
>> 1407 my $args = $3;
1785 1408
1786 if ($identifier ne $declaration_name) { !! 1409 create_parameterlist($args, ',', $file);
1787 emit_warning("${file}:$.", "expecting <<
1788 return; <<
1789 } <<
1790 <<
1791 my $prms = join " ", @parameterlist; <<
1792 check_sections($file, $declaration_name, <<
1793 <<
1794 # This check emits a lot of warnings at t <<
1795 # functions don't have a 'Return' doc sec <<
1796 # of warnings goes sufficiently down, the <<
1797 # -Wreturn mode. <<
1798 # TODO: always perform the check. <<
1799 if ($Wreturn && !$noret) { <<
1800 check_return_section($file, $declarat <<
1801 } <<
1802 <<
1803 # The function parser can be called with <<
1804 # Handle it. <<
1805 if ($return_type =~ /typedef/) { <<
1806 output_declaration($declaration_name, <<
1807 'function', <<
1808 {'function' => $de <<
1809 'typedef' => 1, <<
1810 'module' => $modu <<
1811 'functiontype' => <<
1812 'parameterlist' = <<
1813 'parameterdescs' <<
1814 'parametertypes' <<
1815 'sectionlist' => <<
1816 'sections' => \%s <<
1817 'purpose' => $dec <<
1818 }); <<
1819 } else { 1410 } else {
1820 output_declaration($declaration_name, !! 1411 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1821 'function', !! 1412 ++$errors;
1822 {'function' => $de !! 1413 return;
1823 'module' => $modu !! 1414 }
1824 'functiontype' => !! 1415
1825 'parameterlist' = !! 1416 output_declaration($declaration_name,
1826 'parameterdescs' !! 1417 'function',
1827 'parametertypes' !! 1418 {'function' => $declaration_name,
1828 'sectionlist' => !! 1419 'module' => $modulename,
1829 'sections' => \%s !! 1420 'functiontype' => $return_type,
1830 'purpose' => $dec !! 1421 'parameterlist' => \@parameterlist,
1831 }); !! 1422 'parameterdescs' => \%parameterdescs,
1832 } !! 1423 'parametertypes' => \%parametertypes,
>> 1424 'sectionlist' => \@sectionlist,
>> 1425 'sections' => \%sections,
>> 1426 'purpose' => $declaration_purpose
>> 1427 });
1833 } 1428 }
1834 1429
>> 1430 sub process_file($);
>> 1431
>> 1432 # Read the file that maps relative names to absolute names for
>> 1433 # separate source and object directories and for shadow trees.
>> 1434 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
>> 1435 my ($relname, $absname);
>> 1436 while(<SOURCE_MAP>) {
>> 1437 chop();
>> 1438 ($relname, $absname) = (split())[0..1];
>> 1439 $relname =~ s:^/+::;
>> 1440 $source_map{$relname} = $absname;
>> 1441 }
>> 1442 close(SOURCE_MAP);
>> 1443 }
>> 1444
>> 1445 if ($filelist) {
>> 1446 open(FLIST,"<$filelist") or die "Can't open file list $filelist";
>> 1447 while(<FLIST>) {
>> 1448 chop;
>> 1449 process_file($_);
>> 1450 }
>> 1451 }
>> 1452
>> 1453 foreach (@ARGV) {
>> 1454 chomp;
>> 1455 process_file($_);
>> 1456 }
>> 1457
>> 1458 exit($errors);
>> 1459
1835 sub reset_state { 1460 sub reset_state {
1836 $function = ""; 1461 $function = "";
>> 1462 %constants = ();
1837 %parameterdescs = (); 1463 %parameterdescs = ();
1838 %parametertypes = (); 1464 %parametertypes = ();
1839 @parameterlist = (); 1465 @parameterlist = ();
1840 %sections = (); 1466 %sections = ();
1841 @sectionlist = (); 1467 @sectionlist = ();
1842 $sectcheck = ""; <<
1843 $struct_actual = ""; <<
1844 $prototype = ""; 1468 $prototype = "";
1845 !! 1469
1846 $state = STATE_NORMAL; !! 1470 $state = 0;
1847 $inline_doc_state = STATE_INLINE_NA; <<
1848 } <<
1849 <<
1850 sub tracepoint_munge($) { <<
1851 my $file = shift; <<
1852 my $tracepointname = 0; <<
1853 my $tracepointargs = 0; <<
1854 <<
1855 if ($prototype =~ m/TRACE_EVENT\((.*?),/) <<
1856 $tracepointname = $1; <<
1857 } <<
1858 if ($prototype =~ m/DEFINE_SINGLE_EVENT\( <<
1859 $tracepointname = $1; <<
1860 } <<
1861 if ($prototype =~ m/DEFINE_EVENT\((.*?),( <<
1862 $tracepointname = $2; <<
1863 } <<
1864 $tracepointname =~ s/^\s+//; #strip leadi <<
1865 if ($prototype =~ m/TP_PROTO\((.*?)\)/) { <<
1866 $tracepointargs = $1; <<
1867 } <<
1868 if (($tracepointname eq 0) || ($tracepoin <<
1869 emit_warning("${file}:$.", "Unrecogni <<
1870 "$prototype\n"); <<
1871 } else { <<
1872 $prototype = "static inline void trac <<
1873 $identifier = "trace_$identifier"; <<
1874 } <<
1875 } <<
1876 <<
1877 sub syscall_munge() { <<
1878 my $void = 0; <<
1879 <<
1880 $prototype =~ s@[\r\n]+@ @gos; # strip ne <<
1881 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\ <<
1882 if ($prototype =~ m/SYSCALL_DEFINE0/) { <<
1883 $void = 1; <<
1884 ## $prototype = "long sys_$1(void)"; <<
1885 } <<
1886 <<
1887 $prototype =~ s/SYSCALL_DEFINE.*\(/long s <<
1888 if ($prototype =~ m/long (sys_.*?),/) { <<
1889 $prototype =~ s/,/\(/; <<
1890 } elsif ($void) { <<
1891 $prototype =~ s/\)/\(void\)/; <<
1892 } <<
1893 <<
1894 # now delete all of the odd-number commas <<
1895 # so that arg types & arg names don't hav <<
1896 my $count = 0; <<
1897 my $len = length($prototype); <<
1898 if ($void) { <<
1899 $len = 0; # skip the for-loop <<
1900 } <<
1901 for (my $ix = 0; $ix < $len; $ix++) { <<
1902 if (substr($prototype, $ix, 1) eq ',' <<
1903 $count++; <<
1904 if ($count % 2 == 1) { <<
1905 substr($prototype, $ix, 1) = <<
1906 } <<
1907 } <<
1908 } <<
1909 } 1471 }
1910 1472
1911 sub process_proto_function($$) { !! 1473 sub process_state3_function($$) {
1912 my $x = shift; 1474 my $x = shift;
1913 my $file = shift; 1475 my $file = shift;
1914 1476
1915 $x =~ s@\/\/.*$@@gos; # strip C99-style c !! 1477 if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
1916 !! 1478 # do nothing
1917 if ($x =~ /^#/ && $x !~ /^#\s*define/) { !! 1479 }
1918 # do nothing !! 1480 elsif ($x =~ /([^\{]*)/) {
1919 } elsif ($x =~ /([^\{]*)/) { <<
1920 $prototype .= $1; 1481 $prototype .= $1;
1921 } 1482 }
1922 !! 1483 if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) {
1923 if (($x =~ /\{/) || ($x =~ /\#\s*define/) !! 1484 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1924 $prototype =~ s@/\*.*?\*/@@gos; !! 1485 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1925 $prototype =~ s@[\r\n]+@ @gos; # stri !! 1486 $prototype =~ s@^\s+@@gos; # strip leading spaces
1926 $prototype =~ s@^\s+@@gos; # strip le !! 1487 dump_function($prototype,$file);
1927 !! 1488 reset_state();
1928 # Handle prototypes for function poin <<
1929 # int (*pcs_config)(struct foo) <<
1930 $prototype =~ s@^(\S+\s+)\(\s*\*(\S+) <<
1931 <<
1932 if ($prototype =~ /SYSCALL_DEFINE/) { <<
1933 syscall_munge(); <<
1934 } <<
1935 if ($prototype =~ /TRACE_EVENT/ || $p <<
1936 $prototype =~ /DEFINE_SINGLE_EVEN <<
1937 { <<
1938 tracepoint_munge($file); <<
1939 } <<
1940 dump_function($prototype, $file); <<
1941 reset_state(); <<
1942 } 1489 }
1943 } 1490 }
1944 1491
1945 sub process_proto_type($$) { !! 1492 sub process_state3_type($$) {
1946 my $x = shift; 1493 my $x = shift;
1947 my $file = shift; 1494 my $file = shift;
1948 1495
>> 1496 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1949 $x =~ s@[\r\n]+@ @gos; # strip newlines/c 1497 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1950 $x =~ s@^\s+@@gos; # strip leading spaces 1498 $x =~ s@^\s+@@gos; # strip leading spaces
1951 $x =~ s@\s+$@@gos; # strip trailing space 1499 $x =~ s@\s+$@@gos; # strip trailing spaces
1952 $x =~ s@\/\/.*$@@gos; # strip C99-style c <<
1953 <<
1954 if ($x =~ /^#/) { <<
1955 # To distinguish preprocessor directi <<
1956 $x .= ";"; <<
1957 } <<
1958 1500
1959 while (1) { 1501 while (1) {
1960 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ !! 1502 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1961 if( length $prototype ) { !! 1503 $prototype .= $1 . $2;
1962 $prototype .= " " !! 1504 ($2 eq '{') && $brcount++;
1963 } !! 1505 ($2 eq '}') && $brcount--;
1964 $prototype .= $1 . $2; !! 1506 if (($2 eq ';') && ($brcount == 0)) {
1965 ($2 eq '{') && $brcount++; !! 1507 dump_declaration($prototype,$file);
1966 ($2 eq '}') && $brcount--; !! 1508 reset_state();
1967 if (($2 eq ';') && ($brcount == 0 !! 1509 last;
1968 dump_declaration($prototype, !! 1510 }
1969 reset_state(); !! 1511 $x = $3;
1970 last; !! 1512 } else {
1971 } !! 1513 $prototype .= $x;
1972 $x = $3; !! 1514 last;
1973 } else { !! 1515 }
1974 $prototype .= $x; <<
1975 last; <<
1976 } <<
1977 } 1516 }
1978 } 1517 }
1979 1518
1980 !! 1519 sub process_file($) {
1981 sub map_filename($) { !! 1520 my ($file) = @_;
1982 my $file; !! 1521 my $identifier;
1983 my ($orig_file) = @_; !! 1522 my $func;
1984 !! 1523 my $initial_section_counter = $section_counter;
1985 if (defined($ENV{'SRCTREE'})) { <<
1986 $file = "$ENV{'SRCTREE'}" . "/" . $or <<
1987 } else { <<
1988 $file = $orig_file; <<
1989 } <<
1990 1524
1991 if (defined($source_map{$file})) { 1525 if (defined($source_map{$file})) {
1992 $file = $source_map{$file}; !! 1526 $file = $source_map{$file};
1993 } 1527 }
1994 1528
1995 return $file; <<
1996 } <<
1997 <<
1998 sub process_export_file($) { <<
1999 my ($orig_file) = @_; <<
2000 my $file = map_filename($orig_file); <<
2001 <<
2002 if (!open(IN,"<$file")) { 1529 if (!open(IN,"<$file")) {
2003 print STDERR "Error: Cannot open file !! 1530 print STDERR "Error: Cannot open file $file\n";
2004 ++$errors; !! 1531 ++$errors;
2005 return; !! 1532 return;
2006 } 1533 }
2007 1534
>> 1535 $section_counter = 0;
2008 while (<IN>) { 1536 while (<IN>) {
2009 if (/$export_symbol/) { !! 1537 if ($state == 0) {
2010 next if (defined($nosymbol_table{ !! 1538 if (/$doc_start/o) {
2011 $function_table{$2} = 1; !! 1539 $state = 1; # next line is always the function name
2012 } !! 1540 }
2013 if (/$export_symbol_ns/) { !! 1541 } elsif ($state == 1) { # this line is the function name (always)
2014 next if (defined($nosymbol_table{ !! 1542 if (/$doc_block/o) {
2015 $function_table{$2} = 1; !! 1543 $state = 4;
2016 } !! 1544 $contents = "";
2017 } !! 1545 if ( $1 eq "" ) {
2018 !! 1546 $section = $section_intro;
2019 close(IN); !! 1547 } else {
2020 } !! 1548 $section = $1;
2021 !! 1549 }
2022 # !! 1550 }
2023 # Parsers for the various processing states. !! 1551 elsif (/$doc_decl/o) {
2024 # !! 1552 $identifier = $1;
2025 # STATE_NORMAL: looking for the /** to begin !! 1553 if (/\s*([\w\s]+?)\s*-/) {
2026 # !! 1554 $identifier = $1;
2027 sub process_normal() { !! 1555 }
2028 if (/$doc_start/o) { !! 1556
2029 $state = STATE_NAME; # next li !! 1557 $state = 2;
2030 $in_doc_sect = 0; !! 1558 if (/-(.*)/) {
2031 $declaration_start_line = $. + 1; !! 1559 $declaration_purpose = $1;
2032 } !! 1560 } else {
2033 } !! 1561 $declaration_purpose = "";
2034 !! 1562 }
2035 # !! 1563 if ($identifier =~ m/^struct/) {
2036 # STATE_NAME: Looking for the "name - descrip !! 1564 $decl_type = 'struct';
2037 # !! 1565 } elsif ($identifier =~ m/^union/) {
2038 sub process_name($$) { !! 1566 $decl_type = 'union';
2039 my $file = shift; !! 1567 } elsif ($identifier =~ m/^enum/) {
2040 my $descr; !! 1568 $decl_type = 'enum';
2041 !! 1569 } elsif ($identifier =~ m/^typedef/) {
2042 if (/$doc_block/o) { !! 1570 $decl_type = 'typedef';
2043 $state = STATE_DOCBLOCK; !! 1571 } else {
2044 $contents = ""; !! 1572 $decl_type = 'function';
2045 $new_start_line = $.; !! 1573 }
2046 !! 1574
2047 if ( $1 eq "" ) { !! 1575 if ($verbose) {
2048 $section = $section_intro; !! 1576 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
2049 } else { !! 1577 }
2050 $section = $1; !! 1578 } else {
2051 } !! 1579 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
2052 } elsif (/$doc_decl/o) { !! 1580 " - I thought it was a doc line\n";
2053 $identifier = $1; !! 1581 ++$errors;
2054 my $is_kernel_comment = 0; !! 1582 $state = 0;
2055 my $decl_start = qr{$doc_com}; !! 1583 }
2056 # test for pointer declaration type, !! 1584 } elsif ($state == 2) { # look for head: lines, and include content
2057 my $fn_type = qr{\w+\s*\*\s*}; !! 1585 if (/$doc_sect/o) {
2058 my $parenthesis = qr{\(\w*\)}; !! 1586 $newsection = $1;
2059 my $decl_end = qr{[-:].*}; !! 1587 $newcontents = $2;
2060 if (/^$decl_start([\w\s]+?)$parenthes !! 1588
2061 $identifier = $1; !! 1589 if ($contents ne "") {
2062 } !! 1590 $contents =~ s/\&/\\\\\\amp;/g;
2063 if ($identifier =~ m/^(struct|union|e !! 1591 $contents =~ s/\</\\\\\\lt;/g;
2064 $decl_type = $1; !! 1592 $contents =~ s/\>/\\\\\\gt;/g;
2065 $identifier = $2; !! 1593 dump_section($section, $contents);
2066 $is_kernel_comment = 1; !! 1594 $section = $section_default;
2067 } !! 1595 }
2068 # Look for foo() or static void foo() !! 1596
2069 # identifier !! 1597 $contents = $newcontents;
2070 elsif (/^$decl_start$fn_type?(\w+)\s* !! 1598 if ($contents ne "") {
2071 /^$decl_start$fn_type?(\w+.*)$par !! 1599 $contents .= "\n";
2072 $identifier = $1; !! 1600 }
2073 $decl_type = 'function'; !! 1601 $section = $newsection;
2074 $identifier =~ s/^define\s+//; !! 1602 } elsif (/$doc_end/) {
2075 $is_kernel_comment = 1; !! 1603
2076 } !! 1604 if ($contents ne "") {
2077 $identifier =~ s/\s+$//; !! 1605 $contents =~ s/\&/\\\\\\amp;/g;
2078 !! 1606 $contents =~ s/\</\\\\\\lt;/g;
2079 $state = STATE_BODY; !! 1607 $contents =~ s/\>/\\\\\\gt;/g;
2080 # if there's no @param blocks need to !! 1608 dump_section($section, $contents);
2081 # here !! 1609 $section = $section_default;
2082 $contents = ""; !! 1610 $contents = "";
2083 $section = $section_default; !! 1611 }
2084 $new_start_line = $. + 1; !! 1612
2085 if (/[-:](.*)/) { !! 1613 $prototype = "";
2086 # strip leading/trailing/multiple !! 1614 $state = 3;
2087 $descr= $1; !! 1615 $brcount = 0;
2088 $descr =~ s/^\s*//; !! 1616 # print STDERR "end of doc comment, looking for prototype\n";
2089 $descr =~ s/\s*$//; !! 1617 } elsif (/$doc_content/) {
2090 $descr =~ s/\s+/ /g; !! 1618 # miguel-style comment kludge, look for blank lines after
2091 $declaration_purpose = $descr; !! 1619 # @parameter line to signify start of description
2092 $state = STATE_BODY_MAYBE; !! 1620 if ($1 eq "" &&
2093 } else { !! 1621 ($section =~ m/^@/ || $section eq $section_context)) {
2094 $declaration_purpose = ""; !! 1622 $contents =~ s/\&/\\\\\\amp;/g;
2095 } !! 1623 $contents =~ s/\</\\\\\\lt;/g;
2096 !! 1624 $contents =~ s/\>/\\\\\\gt;/g;
2097 if (!$is_kernel_comment) { !! 1625 dump_section($section, $contents);
2098 emit_warning("${file}:$.", "This !! 1626 $section = $section_default;
2099 $state = STATE_NORMAL; !! 1627 $contents = "";
2100 } !! 1628 } else {
2101 !! 1629 $contents .= $1."\n";
2102 if (($declaration_purpose eq "") && $ !! 1630 }
2103 emit_warning("${file}:$.", "missi !! 1631 } else {
2104 } !! 1632 # i dont know - bad line? ignore.
2105 !! 1633 print STDERR "Warning(${file}:$.): bad line: $_";
2106 if ($identifier eq "" && $decl_type n !! 1634 ++$errors;
2107 emit_warning("${file}:$.", "wrong !! 1635 }
2108 $state = STATE_NORMAL; !! 1636 } elsif ($state == 3) { # scanning for function { (end of prototype)
2109 } !! 1637 if ($decl_type eq 'function') {
2110 !! 1638 process_state3_function($_, $file);
2111 if ($verbose) { !! 1639 } else {
2112 print STDERR "${file}:$.: info: S !! 1640 process_state3_type($_, $file);
2113 } !! 1641 }
2114 } else { !! 1642 } elsif ($state == 4) {
2115 emit_warning("${file}:$.", "Cannot un !! 1643 # Documentation block
2116 $state = STATE_NORMAL; !! 1644 if (/$doc_block/) {
2117 } !! 1645 dump_section($section, $contents);
2118 } !! 1646 output_intro({'sectionlist' => \@sectionlist,
2119 !! 1647 'sections' => \%sections });
2120 !! 1648 $contents = "";
2121 # !! 1649 $function = "";
2122 # STATE_BODY and STATE_BODY_MAYBE: the bulk o !! 1650 %constants = ();
2123 # !! 1651 %parameterdescs = ();
2124 sub process_body($$) { !! 1652 %parametertypes = ();
2125 my $file = shift; !! 1653 @parameterlist = ();
2126 !! 1654 %sections = ();
2127 if ($state == STATE_BODY_WITH_BLANK_LINE !! 1655 @sectionlist = ();
2128 dump_section($file, $section, $conten !! 1656 $prototype = "";
2129 $section = $section_default; !! 1657 if ( $1 eq "" ) {
2130 $new_start_line = $.; !! 1658 $section = $section_intro;
2131 $contents = ""; !! 1659 } else {
2132 } !! 1660 $section = $1;
2133 !! 1661 }
2134 if (/$doc_sect/i) { # case insensitive fo <<
2135 $in_doc_sect = 1; <<
2136 $newsection = $1; <<
2137 $newcontents = $2; <<
2138 <<
2139 # map the supported section names to <<
2140 if ($newsection =~ m/^description$/i) <<
2141 $newsection = $section_default; <<
2142 } elsif ($newsection =~ m/^context$/i <<
2143 $newsection = $section_context; <<
2144 } elsif ($newsection =~ m/^returns?$/ <<
2145 $newsection = $section_return; <<
2146 } elsif ($newsection =~ m/^\@return$/ <<
2147 # special: @return is a section, <<
2148 $newsection = $section_return; <<
2149 } <<
2150 <<
2151 if (($contents ne "") && ($contents n <<
2152 if (!$in_doc_sect && $Wcontents_b <<
2153 emit_warning("${file}:$.", "c <<
2154 } <<
2155 dump_section($file, $section, $co <<
2156 $section = $section_default; <<
2157 } <<
2158 <<
2159 $in_doc_sect = 1; <<
2160 $state = STATE_BODY; <<
2161 $contents = $newcontents; <<
2162 $new_start_line = $.; <<
2163 while (substr($contents, 0, 1) eq " " <<
2164 $contents = substr($contents, 1); <<
2165 } <<
2166 if ($contents ne "") { <<
2167 $contents .= "\n"; <<
2168 } <<
2169 $section = $newsection; <<
2170 $leading_space = undef; <<
2171 } elsif (/$doc_end/) { <<
2172 if (($contents ne "") && ($contents n <<
2173 dump_section($file, $section, $co <<
2174 $section = $section_default; <<
2175 $contents = ""; <<
2176 } <<
2177 # look for doc_com + <text> + doc_end <<
2178 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\ <<
2179 emit_warning("${file}:$.", "suspi <<
2180 } <<
2181 <<
2182 $prototype = ""; <<
2183 $state = STATE_PROTO; <<
2184 $brcount = 0; <<
2185 $new_start_line = $. + 1; <<
2186 } elsif (/$doc_content/) { <<
2187 if ($1 eq "") { <<
2188 if ($section eq $section_context) <<
2189 dump_section($file, $section, <<
2190 $section = $section_default; <<
2191 $contents = ""; <<
2192 $new_start_line = $.; <<
2193 $state = STATE_BODY; <<
2194 } else { <<
2195 if ($section ne $section_defa <<
2196 $state = STATE_BODY_WITH_ <<
2197 } else { <<
2198 $state = STATE_BODY; <<
2199 } <<
2200 $contents .= "\n"; <<
2201 } <<
2202 } elsif ($state == STATE_BODY_MAYBE) <<
2203 # Continued declaration purpose <<
2204 chomp($declaration_purpose); <<
2205 $declaration_purpose .= " " . $1; <<
2206 $declaration_purpose =~ s/\s+/ /g <<
2207 } else { <<
2208 my $cont = $1; <<
2209 if ($section =~ m/^@/ || $section <<
2210 if (!defined $leading_space) <<
2211 if ($cont =~ m/^(\s+)/) { <<
2212 $leading_space = $1; <<
2213 } else { <<
2214 $leading_space = ""; <<
2215 } <<
2216 } 1662 }
2217 $cont =~ s/^$leading_space//; !! 1663 elsif (/$doc_end/)
2218 } !! 1664 {
2219 $contents .= $cont . "\n"; !! 1665 dump_section($section, $contents);
2220 } !! 1666 output_intro({'sectionlist' => \@sectionlist,
2221 } else { !! 1667 'sections' => \%sections });
2222 # i dont know - bad line? ignore. !! 1668 $contents = "";
2223 emit_warning("${file}:$.", "bad line: !! 1669 $function = "";
>> 1670 %constants = ();
>> 1671 %parameterdescs = ();
>> 1672 %parametertypes = ();
>> 1673 @parameterlist = ();
>> 1674 %sections = ();
>> 1675 @sectionlist = ();
>> 1676 $prototype = "";
>> 1677 $state = 0;
>> 1678 }
>> 1679 elsif (/$doc_content/)
>> 1680 {
>> 1681 if ( $1 eq "" )
>> 1682 {
>> 1683 $contents .= $blankline;
>> 1684 }
>> 1685 else
>> 1686 {
>> 1687 $contents .= $1 . "\n";
>> 1688 }
>> 1689 }
>> 1690 }
>> 1691 }
>> 1692 if ($initial_section_counter == $section_counter) {
>> 1693 print STDERR "Warning(${file}): no structured comments found\n";
>> 1694 if ($output_mode eq "sgml") {
>> 1695 # The template wants at least one RefEntry here; make one.
>> 1696 print "<refentry>\n";
>> 1697 print " <refnamediv>\n";
>> 1698 print " <refname>\n";
>> 1699 print " ${file}\n";
>> 1700 print " </refname>\n";
>> 1701 print " <refpurpose>\n";
>> 1702 print " Document generation inconsistency\n";
>> 1703 print " </refpurpose>\n";
>> 1704 print " </refnamediv>\n";
>> 1705 print " <refsect1>\n";
>> 1706 print " <title>\n";
>> 1707 print " Oops\n";
>> 1708 print " </title>\n";
>> 1709 print " <warning>\n";
>> 1710 print " <para>\n";
>> 1711 print " The template for this document tried to insert\n";
>> 1712 print " the structured comment from the file\n";
>> 1713 print " <filename>${file}</filename> at this point,\n";
>> 1714 print " but none was found.\n";
>> 1715 print " This dummy section is inserted to allow\n";
>> 1716 print " generation to continue.\n";
>> 1717 print " </para>\n";
>> 1718 print " </warning>\n";
>> 1719 print " </refsect1>\n";
>> 1720 print "</refentry>\n";
>> 1721 }
2224 } 1722 }
2225 } 1723 }
2226 <<
2227 <<
2228 # <<
2229 # STATE_PROTO: reading a function/whatever pr <<
2230 # <<
2231 sub process_proto($$) { <<
2232 my $file = shift; <<
2233 <<
2234 if (/$doc_inline_oneline/) { <<
2235 $section = $1; <<
2236 $contents = $2; <<
2237 if ($contents ne "") { <<
2238 $contents .= "\n"; <<
2239 dump_section($file, $section, $co <<
2240 $section = $section_default; <<
2241 $contents = ""; <<
2242 } <<
2243 } elsif (/$doc_inline_start/) { <<
2244 $state = STATE_INLINE; <<
2245 $inline_doc_state = STATE_INLINE_NAME <<
2246 } elsif ($decl_type eq 'function') { <<
2247 process_proto_function($_, $file); <<
2248 } else { <<
2249 process_proto_type($_, $file); <<
2250 } <<
2251 } <<
2252 <<
2253 # <<
2254 # STATE_DOCBLOCK: within a DOC: block. <<
2255 # <<
2256 sub process_docblock($$) { <<
2257 my $file = shift; <<
2258 <<
2259 if (/$doc_end/) { <<
2260 dump_doc_section($file, $section, $co <<
2261 $section = $section_default; <<
2262 $contents = ""; <<
2263 $function = ""; <<
2264 %parameterdescs = (); <<
2265 %parametertypes = (); <<
2266 @parameterlist = (); <<
2267 %sections = (); <<
2268 @sectionlist = (); <<
2269 $prototype = ""; <<
2270 $state = STATE_NORMAL; <<
2271 } elsif (/$doc_content/) { <<
2272 if ( $1 eq "" ) { <<
2273 $contents .= $blankline; <<
2274 } else { <<
2275 $contents .= $1 . "\n"; <<
2276 } <<
2277 } <<
2278 } <<
2279 <<
2280 # <<
2281 # STATE_INLINE: docbook comments within a pro <<
2282 # <<
2283 sub process_inline($$) { <<
2284 my $file = shift; <<
2285 <<
2286 # First line (state 1) needs to be a @par <<
2287 if ($inline_doc_state == STATE_INLINE_NAM <<
2288 $section = $1; <<
2289 $contents = $2; <<
2290 $new_start_line = $.; <<
2291 if ($contents ne "") { <<
2292 while (substr($contents, 0, 1) eq <<
2293 $contents = substr($contents, <<
2294 } <<
2295 $contents .= "\n"; <<
2296 } <<
2297 $inline_doc_state = STATE_INLINE_TEXT <<
2298 # Documentation block end */ <<
2299 } elsif (/$doc_inline_end/) { <<
2300 if (($contents ne "") && ($contents n <<
2301 dump_section($file, $section, $co <<
2302 $section = $section_default; <<
2303 $contents = ""; <<
2304 } <<
2305 $state = STATE_PROTO; <<
2306 $inline_doc_state = STATE_INLINE_NA; <<
2307 # Regular text <<
2308 } elsif (/$doc_content/) { <<
2309 if ($inline_doc_state == STATE_INLINE <<
2310 $contents .= $1 . "\n"; <<
2311 # nuke leading blank lines <<
2312 if ($contents =~ /^\s*$/) { <<
2313 $contents = ""; <<
2314 } <<
2315 } elsif ($inline_doc_state == STATE_I <<
2316 $inline_doc_state = STATE_INLINE_ <<
2317 emit_warning("${file}:$.", "Incor <<
2318 } <<
2319 } <<
2320 } <<
2321 <<
2322 <<
2323 sub process_file($) { <<
2324 my $file; <<
2325 my $initial_section_counter = $section_co <<
2326 my ($orig_file) = @_; <<
2327 <<
2328 $file = map_filename($orig_file); <<
2329 <<
2330 if (!open(IN_FILE,"<$file")) { <<
2331 print STDERR "Error: Cannot open file <<
2332 ++$errors; <<
2333 return; <<
2334 } <<
2335 <<
2336 $. = 1; <<
2337 <<
2338 $section_counter = 0; <<
2339 while (<IN_FILE>) { <<
2340 while (!/^ \*/ && s/\\\s*$//) { <<
2341 $_ .= <IN_FILE>; <<
2342 } <<
2343 # Replace tabs by spaces <<
2344 while ($_ =~ s/\t+/' ' x (length($&) <<
2345 # Hand this line to the appropriate s <<
2346 if ($state == STATE_NORMAL) { <<
2347 process_normal(); <<
2348 } elsif ($state == STATE_NAME) { <<
2349 process_name($file, $_); <<
2350 } elsif ($state == STATE_BODY || $sta <<
2351 $state == STATE_BODY_WITH_BL <<
2352 process_body($file, $_); <<
2353 } elsif ($state == STATE_INLINE) { # <<
2354 process_inline($file, $_); <<
2355 } elsif ($state == STATE_PROTO) { <<
2356 process_proto($file, $_); <<
2357 } elsif ($state == STATE_DOCBLOCK) { <<
2358 process_docblock($file, $_); <<
2359 } <<
2360 } <<
2361 <<
2362 # Make sure we got something interesting. <<
2363 if ($initial_section_counter == $section_ <<
2364 output_mode ne "none") { <<
2365 if ($output_selection == OUTPUT_INCLU <<
2366 emit_warning("${file}:1", "'$_' n <<
2367 for keys %function_table; <<
2368 } else { <<
2369 emit_warning("${file}:1", "no str <<
2370 } <<
2371 } <<
2372 close IN_FILE; <<
2373 } <<
2374 <<
2375 <<
2376 if ($output_mode eq "rst") { <<
2377 get_sphinx_version() if (!$sphinx_major); <<
2378 } <<
2379 <<
2380 $kernelversion = get_kernel_version(); <<
2381 <<
2382 # generate a sequence of code that will splic <<
2383 # using the s// operator. <<
2384 for (my $k = 0; $k < @highlights; $k++) { <<
2385 my $pattern = $highlights[$k][0]; <<
2386 my $result = $highlights[$k][1]; <<
2387 # print STDERR "scanning pattern:$pattern, <<
2388 $dohighlight .= "\$contents =~ s:$patter <<
2389 } <<
2390 <<
2391 # Read the file that maps relative names to a <<
2392 # separate source and object directories and <<
2393 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { <<
2394 my ($relname, $absname); <<
2395 while(<SOURCE_MAP>) { <<
2396 chop(); <<
2397 ($relname, $absname) = (split())[0..1 <<
2398 $relname =~ s:^/+::; <<
2399 $source_map{$relname} = $absname; <<
2400 } <<
2401 close(SOURCE_MAP); <<
2402 } <<
2403 <<
2404 if ($output_selection == OUTPUT_EXPORTED || <<
2405 $output_selection == OUTPUT_INTERNAL) { <<
2406 <<
2407 push(@export_file_list, @ARGV); <<
2408 <<
2409 foreach (@export_file_list) { <<
2410 chomp; <<
2411 process_export_file($_); <<
2412 } <<
2413 } <<
2414 <<
2415 foreach (@ARGV) { <<
2416 chomp; <<
2417 process_file($_); <<
2418 } <<
2419 if ($verbose && $errors) { <<
2420 print STDERR "$errors errors\n"; <<
2421 } <<
2422 if ($verbose && $warnings) { <<
2423 print STDERR "$warnings warnings\n"; <<
2424 } <<
2425 <<
2426 if ($Werror && $warnings) { <<
2427 print STDERR "$warnings warnings as Error <<
2428 exit($warnings); <<
2429 } else { <<
2430 exit($output_mode eq "none" ? 0 : $errors <<
2431 } <<
2432 <<
2433 __END__ <<
2434 <<
2435 =head1 OPTIONS <<
2436 <<
2437 =head2 Output format selection (mutually excl <<
2438 <<
2439 =over 8 <<
2440 <<
2441 =item -man <<
2442 <<
2443 Output troff manual page format. <<
2444 <<
2445 =item -rst <<
2446 <<
2447 Output reStructuredText format. This is the d <<
2448 <<
2449 =item -none <<
2450 <<
2451 Do not output documentation, only warnings. <<
2452 <<
2453 =back <<
2454 <<
2455 =head2 Output format modifiers <<
2456 <<
2457 =head3 reStructuredText only <<
2458 <<
2459 =over 8 <<
2460 <<
2461 =item -sphinx-version VERSION <<
2462 <<
2463 Use the ReST C domain dialect compatible with <<
2464 <<
2465 If not specified, kernel-doc will auto-detect <<
2466 found on PATH. <<
2467 <<
2468 =back <<
2469 <<
2470 =head2 Output selection (mutually exclusive): <<
2471 <<
2472 =over 8 <<
2473 <<
2474 =item -export <<
2475 <<
2476 Only output documentation for the symbols tha <<
2477 EXPORT_SYMBOL() and related macros in any inp <<
2478 <<
2479 =item -internal <<
2480 <<
2481 Only output documentation for the symbols tha <<
2482 EXPORT_SYMBOL() and related macros in any inp <<
2483 <<
2484 =item -function NAME <<
2485 <<
2486 Only output documentation for the given funct <<
2487 All other functions and DOC: sections are ign <<
2488 <<
2489 May be specified multiple times. <<
2490 <<
2491 =item -nosymbol NAME <<
2492 <<
2493 Exclude the specified symbol from the output <<
2494 <<
2495 May be specified multiple times. <<
2496 <<
2497 =back <<
2498 <<
2499 =head2 Output selection modifiers: <<
2500 <<
2501 =over 8 <<
2502 <<
2503 =item -no-doc-sections <<
2504 <<
2505 Do not output DOC: sections. <<
2506 <<
2507 =item -export-file FILE <<
2508 <<
2509 Specify an additional FILE in which to look f <<
2510 <<
2511 To be used with -export or -internal. <<
2512 <<
2513 May be specified multiple times. <<
2514 <<
2515 =back <<
2516 <<
2517 =head3 reStructuredText only <<
2518 <<
2519 =over 8 <<
2520 <<
2521 =item -enable-lineno <<
2522 <<
2523 Enable output of .. LINENO lines. <<
2524 <<
2525 =back <<
2526 <<
2527 =head2 Other parameters: <<
2528 <<
2529 =over 8 <<
2530 <<
2531 =item -h, -help <<
2532 <<
2533 Print this help. <<
2534 <<
2535 =item -v <<
2536 <<
2537 Verbose output, more warnings and other infor <<
2538 <<
2539 =item -Werror <<
2540 <<
2541 Treat warnings as errors. <<
2542 <<
2543 =back <<
2544 <<
2545 =cut <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.