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; 157 my $warnings = 0;
61 my $anon_struct_union = 0; <<
62 158
63 # match expressions used to find embedded type 159 # match expressions used to find embedded type information
64 my $type_constant = '\b``([^\`]+)``\b'; !! 160 my $type_constant = '\%([-_\w]+)';
65 my $type_constant2 = '\%([-_*\w]+)'; <<
66 my $type_func = '(\w+)\(\)'; 161 my $type_func = '(\w+)\(\)';
67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\ !! 162 my $type_param = '\@(\w+)';
68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+) !! 163 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+)'; 164 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 165
80 # Output conversion substitutions. 166 # Output conversion substitutions.
81 # One for each output format 167 # One for each output format
82 168
>> 169 # these work fairly well
>> 170 my %highlights_html = ( $type_constant, "<i>\$1</i>",
>> 171 $type_func, "<b>\$1</b>",
>> 172 $type_struct, "<i>\$1</i>",
>> 173 $type_param, "<tt><b>\$1</b></tt>" );
>> 174 my $blankline_html = "<p>";
>> 175
>> 176 # sgml, docbook format
>> 177 my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
>> 178 $type_constant, "<constant>\$1</constant>",
>> 179 $type_func, "<function>\$1</function>",
>> 180 $type_struct, "<structname>\$1</structname>",
>> 181 $type_env, "<envar>\$1</envar>",
>> 182 $type_param, "<parameter>\$1</parameter>" );
>> 183 my $blankline_sgml = "</para><para>\n";
>> 184
>> 185 # gnome, docbook format
>> 186 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
>> 187 $type_func, "<function>\$1</function>",
>> 188 $type_struct, "<structname>\$1</structname>",
>> 189 $type_env, "<envar>\$1</envar>",
>> 190 $type_param, "<parameter>\$1</parameter>" );
>> 191 my $blankline_gnome = "</para><para>\n";
>> 192
83 # these are pretty rough 193 # these are pretty rough
84 my @highlights_man = ( !! 194 my %highlights_man = ( $type_constant, "\$1",
85 [$type_constant, "\$1"], !! 195 $type_func, "\\\\fB\$1\\\\fP",
86 [$type_constant2, "\$1"], !! 196 $type_struct, "\\\\fI\$1\\\\fP",
87 [$type_func, "\\\\fB\$1\\\\fP"], !! 197 $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 = ""; 198 my $blankline_man = "";
98 199
99 # rst-mode !! 200 # text-mode
100 my @highlights_rst = ( !! 201 my %highlights_text = ( $type_constant, "\$1",
101 [$type_constant, "``\$1``"], !! 202 $type_func, "\$1",
102 [$type_constant2, "``\$1``"], !! 203 $type_struct, "\$1",
103 !! 204 $type_param, "\$1" );
104 # Note: need to escape () to avoid func ma !! 205 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 206
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 207
132 my $kernelversion; !! 208 sub usage {
133 my ($sphinx_major, $sphinx_minor, $sphinx_patc !! 209 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
>> 210 print " [ -function funcname [ -function funcname ...] ]\n";
>> 211 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
>> 212 print " c source file(s) > outputfile\n";
>> 213 exit 1;
>> 214 }
134 215
135 my $dohighlight = ""; !! 216 # read arguments
>> 217 if ($#ARGV==-1) {
>> 218 usage();
>> 219 }
136 220
137 my $verbose = 0; 221 my $verbose = 0;
138 my $Werror = 0; !! 222 my $output_mode = "man";
139 my $Wreturn = 0; !! 223 my %highlights = %highlights_man;
140 my $Wshort_desc = 0; !! 224 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"; 225 my $modulename = "Kernel API";
149 !! 226 my $function_only = 0;
150 use constant { !! 227 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
151 OUTPUT_ALL => 0, # output all sym !! 228 'July', 'August', 'September', 'October',
152 OUTPUT_INCLUDE => 1, # output only sp !! 229 'November', 'December')[(localtime)[4]] .
153 OUTPUT_EXPORTED => 2, # output exporte !! 230 " " . ((localtime)[5]+1900);
154 OUTPUT_INTERNAL => 3, # output non-exp !! 231
155 }; !! 232 # Essentially these are globals
156 my $output_selection = OUTPUT_ALL; !! 233 # They probably want to be tidied up made more localised or summat.
157 my $show_not_found = 0; # No longer used !! 234 # 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 235 # could cause "use of undefined value" or other bugs.
178 my ($function, %function_table, %parametertype !! 236 my ($function, %function_table,%parametertypes,$declaration_purpose);
179 my %nosymbol_table = (); !! 237 my ($type,$declaration_name,$return_type);
180 my $declaration_start_line; !! 238 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 239
196 # reading this variable is for backwards compa !! 240 # 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 241 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
207 # https://www.oasis-open.org/docbook/documenta !! 242 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
208 # We keep track of number of generated entries 243 # We keep track of number of generated entries and generate a dummy
209 # if needs be to ensure the expanded template 244 # if needs be to ensure the expanded template can be postprocessed
210 # into html. 245 # into html.
211 my $section_counter = 0; 246 my $section_counter = 0;
212 247
213 my $lineprefix=""; 248 my $lineprefix="";
214 249
215 # Parser states !! 250 # states
216 use constant { !! 251 # 0 - normal code
217 STATE_NORMAL => 0, # normal !! 252 # 1 - looking for function name
218 STATE_NAME => 1, # looking !! 253 # 2 - scanning field start.
219 STATE_BODY_MAYBE => 2, # body - !! 254 # 3 - scanning prototype.
220 STATE_BODY => 3, # the bod !! 255 # 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; 256 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 257
242 #declaration types: can be 258 #declaration types: can be
243 # 'function', 'struct', 'union', 'enum', 'type 259 # 'function', 'struct', 'union', 'enum', 'typedef'
244 my $decl_type; 260 my $decl_type;
245 261
246 # Name of the kernel-doc identifier for non-DO !! 262 my $doc_special = "\@\%\$\&";
247 my $identifier; <<
248 263
249 my $doc_start = '^/\*\*\s*$'; # Allow whitespa 264 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
250 my $doc_end = '\*/'; 265 my $doc_end = '\*/';
251 my $doc_com = '\s*\*\s*'; 266 my $doc_com = '\s*\*\s*';
252 my $doc_com_body = '\s*\* ?'; !! 267 my $doc_decl = $doc_com.'(\w+)';
253 my $doc_decl = $doc_com . '(\w+)'; !! 268 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
254 # @params and a strictly limited set of suppor !! 269 my $doc_content = $doc_com.'(.*)';
255 # Specifically: !! 270 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 271
>> 272 my %constants;
274 my %parameterdescs; 273 my %parameterdescs;
275 my %parameterdesc_start_lines; <<
276 my @parameterlist; 274 my @parameterlist;
277 my %sections; 275 my %sections;
278 my @sectionlist; 276 my @sectionlist;
279 my %section_start_lines; <<
280 my $sectcheck; <<
281 my $struct_actual; <<
282 277
283 my $contents = ""; 278 my $contents = "";
284 my $new_start_line = 0; <<
285 <<
286 # the canonical section names. see also $doc_s <<
287 my $section_default = "Description"; # defa 279 my $section_default = "Description"; # default section
288 my $section_intro = "Introduction"; 280 my $section_intro = "Introduction";
289 my $section = $section_default; 281 my $section = $section_default;
290 my $section_context = "Context"; 282 my $section_context = "Context";
291 my $section_return = "Return"; <<
292 283
293 my $undescribed = "-- undescribed --"; 284 my $undescribed = "-- undescribed --";
294 285
295 reset_state(); 286 reset_state();
296 287
297 while ($ARGV[0] =~ m/^--?(.*)/) { !! 288 while ($ARGV[0] =~ m/^-(.*)/) {
298 my $cmd = $1; !! 289 my $cmd = shift @ARGV;
299 shift @ARGV; !! 290 if ($cmd eq "-html") {
300 if ($cmd eq "man") { !! 291 $output_mode = "html";
301 $output_mode = "man"; !! 292 %highlights = %highlights_html;
302 @highlights = @highlights_man; !! 293 $blankline = $blankline_html;
303 $blankline = $blankline_man; !! 294 } elsif ($cmd eq "-man") {
304 } elsif ($cmd eq "rst") { !! 295 $output_mode = "man";
305 $output_mode = "rst"; !! 296 %highlights = %highlights_man;
306 @highlights = @highlights_rst; !! 297 $blankline = $blankline_man;
307 $blankline = $blankline_rst; !! 298 } elsif ($cmd eq "-text") {
308 } elsif ($cmd eq "none") { !! 299 $output_mode = "text";
309 $output_mode = "none"; !! 300 %highlights = %highlights_text;
310 } elsif ($cmd eq "module") { # not needed !! 301 $blankline = $blankline_text;
311 $modulename = shift @ARGV; !! 302 } elsif ($cmd eq "-docbook") {
312 } elsif ($cmd eq "function") { # to only o !! 303 $output_mode = "sgml";
313 $output_selection = OUTPUT_INCLUDE; !! 304 %highlights = %highlights_sgml;
314 $function = shift @ARGV; !! 305 $blankline = $blankline_sgml;
315 $function_table{$function} = 1; !! 306 } elsif ($cmd eq "-gnome") {
316 } elsif ($cmd eq "nosymbol") { # Exclude s !! 307 $output_mode = "gnome";
317 my $symbol = shift @ARGV; !! 308 %highlights = %highlights_gnome;
318 $nosymbol_table{$symbol} = 1; !! 309 $blankline = $blankline_gnome;
319 } elsif ($cmd eq "export") { # only export !! 310 } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
320 $output_selection = OUTPUT_EXPORTED; !! 311 $modulename = shift @ARGV;
321 %function_table = (); !! 312 } elsif ($cmd eq "-function") { # to only output specific functions
322 } elsif ($cmd eq "internal") { # only non- !! 313 $function_only = 1;
323 $output_selection = OUTPUT_INTERNAL; !! 314 $function = shift @ARGV;
324 %function_table = (); !! 315 $function_table{$function} = 1;
325 } elsif ($cmd eq "export-file") { !! 316 } elsif ($cmd eq "-nofunction") { # to only output specific functions
326 my $file = shift @ARGV; !! 317 $function_only = 2;
327 push(@export_file_list, $file); !! 318 $function = shift @ARGV;
328 } elsif ($cmd eq "v") { !! 319 $function_table{$function} = 1;
329 $verbose = 1; !! 320 } elsif ($cmd eq "-v") {
330 } elsif ($cmd eq "Werror") { !! 321 $verbose = 1;
331 $Werror = 1; !! 322 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
332 } elsif ($cmd eq "Wreturn") { !! 323 usage();
333 $Wreturn = 1; !! 324 } elsif ($cmd eq '-filelist') {
334 } elsif ($cmd eq "Wshort-desc" or $cmd eq !! 325 $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 } <<
397 } <<
398 <<
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 <<
416 open IN, "$cmd --version 2>&1 |"; <<
417 while (<IN>) { <<
418 if (m/^\s*sphinx-build\s+([\d]+)\.([\d <<
419 $sphinx_major = $1; <<
420 $sphinx_minor = $2; <<
421 $sphinx_patch = $3; <<
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 } 326 }
432 close IN; <<
433 } 327 }
434 328
435 # get kernel version from env <<
436 sub get_kernel_version() { <<
437 my $version = 'unknown kernel version'; <<
438 329
439 if (defined($ENV{'KERNELVERSION'})) { !! 330 # generate a sequence of code that will splice in highlighting information
440 $version = $ENV{'KERNELVERSION'}; !! 331 # using the s// operator.
441 } !! 332 my $dohighlight = "";
442 return $version; !! 333 foreach my $pattern (keys %highlights) {
443 } !! 334 # print "scanning pattern $pattern ($highlights{$pattern})\n";
444 !! 335 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
445 # <<
446 sub print_lineno { <<
447 my $lineno = shift; <<
448 if ($enable_lineno && defined($lineno)) { <<
449 print ".. LINENO " . $lineno . "\n"; <<
450 } <<
451 } 336 }
452 337
453 sub emit_warning { <<
454 my $location = shift; <<
455 my $msg = shift; <<
456 print STDERR "$location: warning: $msg"; <<
457 ++$warnings; <<
458 } <<
459 ## 338 ##
460 # dumps section contents to arrays/hashes inte 339 # dumps section contents to arrays/hashes intended for that purpose.
461 # 340 #
462 sub dump_section { 341 sub dump_section {
463 my $file = shift; <<
464 my $name = shift; 342 my $name = shift;
465 my $contents = join "\n", @_; 343 my $contents = join "\n", @_;
466 344
467 if ($name =~ m/$type_param/) { !! 345 if ($name =~ m/$type_constant/) {
468 $name = $1; !! 346 $name = $1;
469 $parameterdescs{$name} = $contents; !! 347 # print STDERR "constant section '$1' = '$contents'\n";
470 $sectcheck = $sectcheck . $name . " "; !! 348 $constants{$name} = $contents;
471 $parameterdesc_start_lines{$name} = $n !! 349 } elsif ($name =~ m/$type_param/) {
472 $new_start_line = 0; !! 350 # print STDERR "parameter def '$1' = '$contents'\n";
473 } elsif ($name eq "@\.\.\.") { !! 351 $name = $1;
474 $name = "..."; !! 352 $parameterdescs{$name} = $contents;
475 $parameterdescs{$name} = $contents; <<
476 $sectcheck = $sectcheck . $name . " "; <<
477 $parameterdesc_start_lines{$name} = $n <<
478 $new_start_line = 0; <<
479 } else { 353 } else {
480 if (defined($sections{$name}) && ($sec !! 354 # print STDERR "other section '$name' = '$contents'\n";
481 # Only warn on user specified dupl !! 355 $sections{$name} = $contents;
482 if ($name ne $section_default) { !! 356 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 } 357 }
519 } 358 }
520 359
521 ## 360 ##
522 # output function 361 # output function
523 # 362 #
524 # parameterdescs, a hash. 363 # parameterdescs, a hash.
525 # function => "function name" 364 # function => "function name"
526 # parameterlist => @list of parameters 365 # parameterlist => @list of parameters
527 # parameterdescs => %parameter descriptions 366 # parameterdescs => %parameter descriptions
528 # sectionlist => @list of sections 367 # sectionlist => @list of sections
529 # sections => %section descriptions !! 368 # sections => %descriont descriptions
530 # !! 369 #
531 370
532 sub output_highlight { 371 sub output_highlight {
533 my $contents = join "\n",@_; 372 my $contents = join "\n",@_;
534 my $line; 373 my $line;
535 374
536 # DEBUG 375 # DEBUG
537 # if (!defined $contents) { 376 # if (!defined $contents) {
538 # use Carp; 377 # use Carp;
539 # confess "output_highlight got called w 378 # confess "output_highlight got called with no args?\n";
540 # } 379 # }
541 380
542 # print STDERR "contents b4:$contents\n"; <<
543 eval $dohighlight; 381 eval $dohighlight;
544 die $@ if $@; 382 die $@ if $@;
545 # print STDERR "contents af:$contents\n"; <<
546 <<
547 foreach $line (split "\n", $contents) { 383 foreach $line (split "\n", $contents) {
548 if (! $output_preformatted) { !! 384 if ($line eq ""){
549 $line =~ s/^\s*//; !! 385 print $lineprefix, $blankline;
550 } !! 386 } else {
551 if ($line eq ""){ !! 387 $line =~ s/\\\\\\/\&/g;
552 if (! $output_preformatted) { !! 388 print $lineprefix, $line;
553 print $lineprefix, $blankline; !! 389 }
554 } !! 390 print "\n";
555 } else { <<
556 if ($output_mode eq "man" && subst <<
557 print "\\&$line"; <<
558 } else { <<
559 print $lineprefix, $line; <<
560 } <<
561 } <<
562 print "\n"; <<
563 } 391 }
564 } 392 }
565 393
>> 394 #output sections in html
>> 395 sub output_section_html(%) {
>> 396 my %args = %{$_[0]};
>> 397 my $section;
>> 398
>> 399 foreach $section (@{$args{'sectionlist'}}) {
>> 400 print "<h3>$section</h3>\n";
>> 401 print "<blockquote>\n";
>> 402 output_highlight($args{'sections'}{$section});
>> 403 print "</blockquote>\n";
>> 404 }
>> 405 }
>> 406
>> 407 # output enum in html
>> 408 sub output_enum_html(%) {
>> 409 my %args = %{$_[0]};
>> 410 my ($parameter);
>> 411 my $count;
>> 412 print "<h2>enum ".$args{'enum'}."</h2>\n";
>> 413
>> 414 print "<b>enum ".$args{'enum'}."</b> {<br>\n";
>> 415 $count = 0;
>> 416 foreach $parameter (@{$args{'parameterlist'}}) {
>> 417 print " <b>".$parameter."</b>";
>> 418 if ($count != $#{$args{'parameterlist'}}) {
>> 419 $count++;
>> 420 print ",\n";
>> 421 }
>> 422 print "<br>";
>> 423 }
>> 424 print "};<br>\n";
>> 425
>> 426 print "<h3>Constants</h3>\n";
>> 427 print "<dl>\n";
>> 428 foreach $parameter (@{$args{'parameterlist'}}) {
>> 429 print "<dt><b>".$parameter."</b>\n";
>> 430 print "<dd>";
>> 431 output_highlight($args{'parameterdescs'}{$parameter});
>> 432 }
>> 433 print "</dl>\n";
>> 434 output_section_html(@_);
>> 435 print "<hr>\n";
>> 436 }
>> 437
>> 438 # output tyepdef in html
>> 439 sub output_typedef_html(%) {
>> 440 my %args = %{$_[0]};
>> 441 my ($parameter);
>> 442 my $count;
>> 443 print "<h2>typedef ".$args{'typedef'}."</h2>\n";
>> 444
>> 445 print "<b>typedef ".$args{'typedef'}."</b>\n";
>> 446 output_section_html(@_);
>> 447 print "<hr>\n";
>> 448 }
>> 449
>> 450 # output struct in html
>> 451 sub output_struct_html(%) {
>> 452 my %args = %{$_[0]};
>> 453 my ($parameter);
>> 454
>> 455 print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
>> 456 print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
>> 457 foreach $parameter (@{$args{'parameterlist'}}) {
>> 458 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 459 $type = $args{'parametertypes'}{$parameter};
>> 460 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 461 # pointer-to-function
>> 462 print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
>> 463 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 464 print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
>> 465 } else {
>> 466 print " <i>$type</i> <b>$parameter</b>;<br>\n";
>> 467 }
>> 468 }
>> 469 print "};<br>\n";
>> 470
>> 471 print "<h3>Members</h3>\n";
>> 472 print "<dl>\n";
>> 473 foreach $parameter (@{$args{'parameterlist'}}) {
>> 474 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 475 print "<dt><b>".$parameter."</b>\n";
>> 476 print "<dd>";
>> 477 output_highlight($args{'parameterdescs'}{$parameter});
>> 478 }
>> 479 print "</dl>\n";
>> 480 output_section_html(@_);
>> 481 print "<hr>\n";
>> 482 }
>> 483
>> 484 # output function in html
>> 485 sub output_function_html(%) {
>> 486 my %args = %{$_[0]};
>> 487 my ($parameter, $section);
>> 488 my $count;
>> 489 print "<h2>Function</h2>\n";
>> 490
>> 491 print "<i>".$args{'functiontype'}."</i>\n";
>> 492 print "<b>".$args{'function'}."</b>\n";
>> 493 print "(";
>> 494 $count = 0;
>> 495 foreach $parameter (@{$args{'parameterlist'}}) {
>> 496 $type = $args{'parametertypes'}{$parameter};
>> 497 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 498 # pointer-to-function
>> 499 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
>> 500 } else {
>> 501 print "<i>".$type."</i> <b>".$parameter."</b>";
>> 502 }
>> 503 if ($count != $#{$args{'parameterlist'}}) {
>> 504 $count++;
>> 505 print ",\n";
>> 506 }
>> 507 }
>> 508 print ")\n";
>> 509
>> 510 print "<h3>Arguments</h3>\n";
>> 511 print "<dl>\n";
>> 512 foreach $parameter (@{$args{'parameterlist'}}) {
>> 513 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 514 print "<dt><b>".$parameter."</b>\n";
>> 515 print "<dd>";
>> 516 output_highlight($args{'parameterdescs'}{$parameter});
>> 517 }
>> 518 print "</dl>\n";
>> 519 output_section_html(@_);
>> 520 print "<hr>\n";
>> 521 }
>> 522
>> 523 # output intro in html
>> 524 sub output_intro_html(%) {
>> 525 my %args = %{$_[0]};
>> 526 my ($parameter, $section);
>> 527 my $count;
>> 528
>> 529 foreach $section (@{$args{'sectionlist'}}) {
>> 530 print "<h3>$section</h3>\n";
>> 531 print "<ul>\n";
>> 532 output_highlight($args{'sections'}{$section});
>> 533 print "</ul>\n";
>> 534 }
>> 535 print "<hr>\n";
>> 536 }
>> 537
>> 538 sub output_section_sgml(%) {
>> 539 my %args = %{$_[0]};
>> 540 my $section;
>> 541 # print out each section
>> 542 $lineprefix=" ";
>> 543 foreach $section (@{$args{'sectionlist'}}) {
>> 544 print "<refsect1>\n <title>$section</title>\n <para>\n";
>> 545 if ($section =~ m/EXAMPLE/i) {
>> 546 print "<example><para>\n";
>> 547 }
>> 548 output_highlight($args{'sections'}{$section});
>> 549 if ($section =~ m/EXAMPLE/i) {
>> 550 print "</para></example>\n";
>> 551 }
>> 552 print " </para>\n</refsect1>\n";
>> 553 }
>> 554 }
>> 555
>> 556 # output function in sgml DocBook
>> 557 sub output_function_sgml(%) {
>> 558 my %args = %{$_[0]};
>> 559 my ($parameter, $section);
>> 560 my $count;
>> 561 my $id;
>> 562
>> 563 $id = "API-".$args{'function'};
>> 564 $id =~ s/[^A-Za-z0-9]/-/g;
>> 565
>> 566 print "<refentry>\n";
>> 567 print "<refmeta>\n";
>> 568 print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
>> 569 print "</refmeta>\n";
>> 570 print "<refnamediv>\n";
>> 571 print " <refname>".$args{'function'}."</refname>\n";
>> 572 print " <refpurpose>\n";
>> 573 print " ";
>> 574 output_highlight ($args{'purpose'});
>> 575 print " </refpurpose>\n";
>> 576 print "</refnamediv>\n";
>> 577
>> 578 print "<refsynopsisdiv>\n";
>> 579 print " <title>Synopsis</title>\n";
>> 580 print " <funcsynopsis><funcprototype>\n";
>> 581 print " <funcdef>".$args{'functiontype'}." ";
>> 582 print "<function>".$args{'function'}." </function></funcdef>\n";
>> 583
>> 584 $count = 0;
>> 585 if ($#{$args{'parameterlist'}} >= 0) {
>> 586 foreach $parameter (@{$args{'parameterlist'}}) {
>> 587 $type = $args{'parametertypes'}{$parameter};
>> 588 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 589 # pointer-to-function
>> 590 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
>> 591 print " <funcparams>$2</funcparams></paramdef>\n";
>> 592 } else {
>> 593 print " <paramdef>".$type;
>> 594 print " <parameter>$parameter</parameter></paramdef>\n";
>> 595 }
>> 596 }
>> 597 } else {
>> 598 print " <void>\n";
>> 599 }
>> 600 print " </funcprototype></funcsynopsis>\n";
>> 601 print "</refsynopsisdiv>\n";
>> 602
>> 603 # print parameters
>> 604 print "<refsect1>\n <title>Arguments</title>\n";
>> 605 if ($#{$args{'parameterlist'}} >= 0) {
>> 606 print " <variablelist>\n";
>> 607 foreach $parameter (@{$args{'parameterlist'}}) {
>> 608 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
>> 609 print " <listitem>\n <para>\n";
>> 610 $lineprefix=" ";
>> 611 output_highlight($args{'parameterdescs'}{$parameter});
>> 612 print " </para>\n </listitem>\n </varlistentry>\n";
>> 613 }
>> 614 print " </variablelist>\n";
>> 615 } else {
>> 616 print " <para>\n None\n </para>\n";
>> 617 }
>> 618 print "</refsect1>\n";
>> 619
>> 620 output_section_sgml(@_);
>> 621 print "</refentry>\n\n";
>> 622 }
>> 623
>> 624 # output struct in sgml DocBook
>> 625 sub output_struct_sgml(%) {
>> 626 my %args = %{$_[0]};
>> 627 my ($parameter, $section);
>> 628 my $id;
>> 629
>> 630 $id = "API-struct-".$args{'struct'};
>> 631 $id =~ s/[^A-Za-z0-9]/-/g;
>> 632
>> 633 print "<refentry>\n";
>> 634 print "<refmeta>\n";
>> 635 print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
>> 636 print "</refmeta>\n";
>> 637 print "<refnamediv>\n";
>> 638 print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
>> 639 print " <refpurpose>\n";
>> 640 print " ";
>> 641 output_highlight ($args{'purpose'});
>> 642 print " </refpurpose>\n";
>> 643 print "</refnamediv>\n";
>> 644
>> 645 print "<refsynopsisdiv>\n";
>> 646 print " <title>Synopsis</title>\n";
>> 647 print " <programlisting>\n";
>> 648 print $args{'type'}." ".$args{'struct'}." {\n";
>> 649 foreach $parameter (@{$args{'parameterlist'}}) {
>> 650 defined($args{'parameterdescs'}{$parameter}) || next;
>> 651 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 652 $type = $args{'parametertypes'}{$parameter};
>> 653 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 654 # pointer-to-function
>> 655 print " $1 $parameter ($2);\n";
>> 656 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 657 print " $1 $parameter$2;\n";
>> 658 } else {
>> 659 print " ".$type." ".$parameter.";\n";
>> 660 }
>> 661 }
>> 662 print "};";
>> 663 print " </programlisting>\n";
>> 664 print "</refsynopsisdiv>\n";
>> 665
>> 666 print " <refsect1>\n";
>> 667 print " <title>Members</title>\n";
>> 668
>> 669 print " <variablelist>\n";
>> 670 foreach $parameter (@{$args{'parameterlist'}}) {
>> 671 defined($args{'parameterdescs'}{$parameter}) || next;
>> 672 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 673 print " <varlistentry>";
>> 674 print " <term>$parameter</term>\n";
>> 675 print " <listitem><para>\n";
>> 676 output_highlight($args{'parameterdescs'}{$parameter});
>> 677 print " </para></listitem>\n";
>> 678 print " </varlistentry>\n";
>> 679 }
>> 680 print " </variablelist>\n";
>> 681 print " </refsect1>\n";
>> 682
>> 683 output_section_sgml(@_);
>> 684
>> 685 print "</refentry>\n\n";
>> 686 }
>> 687
>> 688 # output enum in sgml DocBook
>> 689 sub output_enum_sgml(%) {
>> 690 my %args = %{$_[0]};
>> 691 my ($parameter, $section);
>> 692 my $count;
>> 693 my $id;
>> 694
>> 695 $id = "API-enum-".$args{'enum'};
>> 696 $id =~ s/[^A-Za-z0-9]/-/g;
>> 697
>> 698 print "<refentry>\n";
>> 699 print "<refmeta>\n";
>> 700 print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
>> 701 print "</refmeta>\n";
>> 702 print "<refnamediv>\n";
>> 703 print " <refname>enum ".$args{'enum'}."</refname>\n";
>> 704 print " <refpurpose>\n";
>> 705 print " ";
>> 706 output_highlight ($args{'purpose'});
>> 707 print " </refpurpose>\n";
>> 708 print "</refnamediv>\n";
>> 709
>> 710 print "<refsynopsisdiv>\n";
>> 711 print " <title>Synopsis</title>\n";
>> 712 print " <programlisting>\n";
>> 713 print "enum ".$args{'enum'}." {\n";
>> 714 $count = 0;
>> 715 foreach $parameter (@{$args{'parameterlist'}}) {
>> 716 print " $parameter";
>> 717 if ($count != $#{$args{'parameterlist'}}) {
>> 718 $count++;
>> 719 print ",";
>> 720 }
>> 721 print "\n";
>> 722 }
>> 723 print "};";
>> 724 print " </programlisting>\n";
>> 725 print "</refsynopsisdiv>\n";
>> 726
>> 727 print "<refsect1>\n";
>> 728 print " <title>Constants</title>\n";
>> 729 print " <variablelist>\n";
>> 730 foreach $parameter (@{$args{'parameterlist'}}) {
>> 731 print " <varlistentry>";
>> 732 print " <term>$parameter</term>\n";
>> 733 print " <listitem><para>\n";
>> 734 output_highlight($args{'parameterdescs'}{$parameter});
>> 735 print " </para></listitem>\n";
>> 736 print " </varlistentry>\n";
>> 737 }
>> 738 print " </variablelist>\n";
>> 739 print "</refsect1>\n";
>> 740
>> 741 output_section_sgml(@_);
>> 742
>> 743 print "</refentry>\n\n";
>> 744 }
>> 745
>> 746 # output typedef in sgml DocBook
>> 747 sub output_typedef_sgml(%) {
>> 748 my %args = %{$_[0]};
>> 749 my ($parameter, $section);
>> 750 my $id;
>> 751
>> 752 $id = "API-typedef-".$args{'typedef'};
>> 753 $id =~ s/[^A-Za-z0-9]/-/g;
>> 754
>> 755 print "<refentry>\n";
>> 756 print "<refmeta>\n";
>> 757 print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
>> 758 print "</refmeta>\n";
>> 759 print "<refnamediv>\n";
>> 760 print " <refname>typedef ".$args{'typedef'}."</refname>\n";
>> 761 print " <refpurpose>\n";
>> 762 print " ";
>> 763 output_highlight ($args{'purpose'});
>> 764 print " </refpurpose>\n";
>> 765 print "</refnamediv>\n";
>> 766
>> 767 print "<refsynopsisdiv>\n";
>> 768 print " <title>Synopsis</title>\n";
>> 769 print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
>> 770 print "</refsynopsisdiv>\n";
>> 771
>> 772 output_section_sgml(@_);
>> 773
>> 774 print "</refentry>\n\n";
>> 775 }
>> 776
>> 777 # output in sgml DocBook
>> 778 sub output_intro_sgml(%) {
>> 779 my %args = %{$_[0]};
>> 780 my ($parameter, $section);
>> 781 my $count;
>> 782
>> 783 my $id = $args{'module'};
>> 784 $id =~ s/[^A-Za-z0-9]/-/g;
>> 785
>> 786 # print out each section
>> 787 $lineprefix=" ";
>> 788 foreach $section (@{$args{'sectionlist'}}) {
>> 789 print "<refsect1>\n <title>$section</title>\n <para>\n";
>> 790 if ($section =~ m/EXAMPLE/i) {
>> 791 print "<example><para>\n";
>> 792 }
>> 793 output_highlight($args{'sections'}{$section});
>> 794 if ($section =~ m/EXAMPLE/i) {
>> 795 print "</para></example>\n";
>> 796 }
>> 797 print " </para>\n</refsect1>\n";
>> 798 }
>> 799
>> 800 print "\n\n";
>> 801 }
>> 802
>> 803 # output in sgml DocBook
>> 804 sub output_function_gnome {
>> 805 my %args = %{$_[0]};
>> 806 my ($parameter, $section);
>> 807 my $count;
>> 808 my $id;
>> 809
>> 810 $id = $args{'module'}."-".$args{'function'};
>> 811 $id =~ s/[^A-Za-z0-9]/-/g;
>> 812
>> 813 print "<sect2>\n";
>> 814 print " <title id=\"$id\">".$args{'function'}."</title>\n";
>> 815
>> 816 print " <funcsynopsis>\n";
>> 817 print " <funcdef>".$args{'functiontype'}." ";
>> 818 print "<function>".$args{'function'}." ";
>> 819 print "</function></funcdef>\n";
>> 820
>> 821 $count = 0;
>> 822 if ($#{$args{'parameterlist'}} >= 0) {
>> 823 foreach $parameter (@{$args{'parameterlist'}}) {
>> 824 $type = $args{'parametertypes'}{$parameter};
>> 825 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 826 # pointer-to-function
>> 827 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
>> 828 print " <funcparams>$2</funcparams></paramdef>\n";
>> 829 } else {
>> 830 print " <paramdef>".$type;
>> 831 print " <parameter>$parameter</parameter></paramdef>\n";
>> 832 }
>> 833 }
>> 834 } else {
>> 835 print " <void>\n";
>> 836 }
>> 837 print " </funcsynopsis>\n";
>> 838 if ($#{$args{'parameterlist'}} >= 0) {
>> 839 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
>> 840 print "<tgroup cols=\"2\">\n";
>> 841 print "<colspec colwidth=\"2*\">\n";
>> 842 print "<colspec colwidth=\"8*\">\n";
>> 843 print "<tbody>\n";
>> 844 foreach $parameter (@{$args{'parameterlist'}}) {
>> 845 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
>> 846 print " <entry>\n";
>> 847 $lineprefix=" ";
>> 848 output_highlight($args{'parameterdescs'}{$parameter});
>> 849 print " </entry></row>\n";
>> 850 }
>> 851 print " </tbody></tgroup></informaltable>\n";
>> 852 } else {
>> 853 print " <para>\n None\n </para>\n";
>> 854 }
>> 855
>> 856 # print out each section
>> 857 $lineprefix=" ";
>> 858 foreach $section (@{$args{'sectionlist'}}) {
>> 859 print "<simplesect>\n <title>$section</title>\n";
>> 860 if ($section =~ m/EXAMPLE/i) {
>> 861 print "<example><programlisting>\n";
>> 862 } else {
>> 863 }
>> 864 print "<para>\n";
>> 865 output_highlight($args{'sections'}{$section});
>> 866 print "</para>\n";
>> 867 if ($section =~ m/EXAMPLE/i) {
>> 868 print "</programlisting></example>\n";
>> 869 } else {
>> 870 }
>> 871 print " </simplesect>\n";
>> 872 }
>> 873
>> 874 print "</sect2>\n\n";
>> 875 }
>> 876
566 ## 877 ##
567 # output function in man 878 # output function in man
568 sub output_function_man(%) { 879 sub output_function_man(%) {
569 my %args = %{$_[0]}; 880 my %args = %{$_[0]};
570 my ($parameter, $section); 881 my ($parameter, $section);
571 my $count; 882 my $count;
572 883
573 print ".TH \"$args{'function'}\" 9 \"$args 884 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
574 885
575 print ".SH NAME\n"; 886 print ".SH NAME\n";
576 print $args{'function'} . " \\- " . $args{ !! 887 print $args{'function'}." \\- ".$args{'purpose'}."\n";
577 888
578 print ".SH SYNOPSIS\n"; 889 print ".SH SYNOPSIS\n";
579 if ($args{'functiontype'} ne "") { !! 890 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
580 print ".B \"" . $args{'functiontype'} <<
581 } else { <<
582 print ".B \"" . $args{'function'} . "\ <<
583 } <<
584 $count = 0; 891 $count = 0;
585 my $parenth = "("; 892 my $parenth = "(";
586 my $post = ","; 893 my $post = ",";
587 foreach my $parameter (@{$args{'parameterl 894 foreach my $parameter (@{$args{'parameterlist'}}) {
588 if ($count == $#{$args{'parameterlist' !! 895 if ($count == $#{$args{'parameterlist'}}) {
589 $post = ");"; !! 896 $post = ");";
590 } !! 897 }
591 $type = $args{'parametertypes'}{$param !! 898 $type = $args{'parametertypes'}{$parameter};
592 if ($type =~ m/$function_pointer/) { !! 899 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
593 # pointer-to-function !! 900 # pointer-to-function
594 print ".BI \"" . $parenth . $1 . " !! 901 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
595 } else { !! 902 } else {
596 $type =~ s/([^\*])$/$1 /; !! 903 $type =~ s/([^\*])$/$1 /;
597 print ".BI \"" . $parenth . $type !! 904 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
598 } !! 905 }
599 $count++; !! 906 $count++;
600 $parenth = ""; !! 907 $parenth = "";
601 } 908 }
602 909
603 print ".SH ARGUMENTS\n"; 910 print ".SH ARGUMENTS\n";
604 foreach $parameter (@{$args{'parameterlist 911 foreach $parameter (@{$args{'parameterlist'}}) {
605 my $parameter_name = $parameter; !! 912 print ".IP \"".$parameter."\" 12\n";
606 $parameter_name =~ s/\[.*//; !! 913 output_highlight($args{'parameterdescs'}{$parameter});
607 <<
608 print ".IP \"" . $parameter . "\" 12\n <<
609 output_highlight($args{'parameterdescs <<
610 } 914 }
611 foreach $section (@{$args{'sectionlist'}}) 915 foreach $section (@{$args{'sectionlist'}}) {
612 print ".SH \"", uc $section, "\"\n"; !! 916 print ".SH \"", uc $section, "\"\n";
613 output_highlight($args{'sections'}{$se !! 917 output_highlight($args{'sections'}{$section});
614 } 918 }
615 } 919 }
616 920
617 ## 921 ##
618 # output enum in man 922 # output enum in man
619 sub output_enum_man(%) { 923 sub output_enum_man(%) {
620 my %args = %{$_[0]}; 924 my %args = %{$_[0]};
621 my ($parameter, $section); 925 my ($parameter, $section);
622 my $count; 926 my $count;
623 927
624 print ".TH \"$args{'module'}\" 9 \"enum $a 928 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
625 929
626 print ".SH NAME\n"; 930 print ".SH NAME\n";
627 print "enum " . $args{'enum'} . " \\- " . !! 931 print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
628 932
629 print ".SH SYNOPSIS\n"; 933 print ".SH SYNOPSIS\n";
630 print "enum " . $args{'enum'} . " {\n"; !! 934 print "enum ".$args{'enum'}." {\n";
631 $count = 0; 935 $count = 0;
632 foreach my $parameter (@{$args{'parameterl 936 foreach my $parameter (@{$args{'parameterlist'}}) {
633 print ".br\n.BI \" $parameter\"\n"; 937 print ".br\n.BI \" $parameter\"\n";
634 if ($count == $#{$args{'parameterlist' !! 938 if ($count == $#{$args{'parameterlist'}}) {
635 print "\n};\n"; !! 939 print "\n};\n";
636 last; !! 940 last;
637 } else { !! 941 }
638 print ", \n.br\n"; !! 942 else {
639 } !! 943 print ", \n.br\n";
640 $count++; !! 944 }
>> 945 $count++;
641 } 946 }
642 947
643 print ".SH Constants\n"; 948 print ".SH Constants\n";
644 foreach $parameter (@{$args{'parameterlist 949 foreach $parameter (@{$args{'parameterlist'}}) {
645 my $parameter_name = $parameter; !! 950 print ".IP \"".$parameter."\" 12\n";
646 $parameter_name =~ s/\[.*//; !! 951 output_highlight($args{'parameterdescs'}{$parameter});
647 <<
648 print ".IP \"" . $parameter . "\" 12\n <<
649 output_highlight($args{'parameterdescs <<
650 } 952 }
651 foreach $section (@{$args{'sectionlist'}}) 953 foreach $section (@{$args{'sectionlist'}}) {
652 print ".SH \"$section\"\n"; !! 954 print ".SH \"$section\"\n";
653 output_highlight($args{'sections'}{$se !! 955 output_highlight($args{'sections'}{$section});
654 } 956 }
655 } 957 }
656 958
657 ## 959 ##
658 # output struct in man 960 # output struct in man
659 sub output_struct_man(%) { 961 sub output_struct_man(%) {
660 my %args = %{$_[0]}; 962 my %args = %{$_[0]};
661 my ($parameter, $section); 963 my ($parameter, $section);
662 964
663 print ".TH \"$args{'module'}\" 9 \"" . $ar !! 965 print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
664 966
665 print ".SH NAME\n"; 967 print ".SH NAME\n";
666 print $args{'type'} . " " . $args{'struct' !! 968 print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
667 969
668 my $declaration = $args{'definition'}; <<
669 $declaration =~ s/\t/ /g; <<
670 $declaration =~ s/\n/"\n.br\n.BI \"/g; <<
671 print ".SH SYNOPSIS\n"; 970 print ".SH SYNOPSIS\n";
672 print $args{'type'} . " " . $args{'struct' !! 971 print $args{'type'}." ".$args{'struct'}." {\n";
673 print ".BI \"$declaration\n};\n.br\n\n"; <<
674 972
675 print ".SH Members\n"; !! 973 foreach my $parameter (@{$args{'parameterlist'}}) {
676 foreach $parameter (@{$args{'parameterlist !! 974 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
677 ($parameter =~ /^#/) && next; !! 975 print "\n.br\n";
678 !! 976 $type = $args{'parametertypes'}{$parameter};
679 my $parameter_name = $parameter; !! 977 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
680 $parameter_name =~ s/\[.*//; !! 978 # pointer-to-function
>> 979 print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
>> 980 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 981 print ".BI \" ".$1."\" ".$parameter.$2." \""."\"\n;\n";
>> 982 } else {
>> 983 $type =~ s/([^\*])$/$1 /;
>> 984 print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
>> 985 }
>> 986 print "\n.br\n";
>> 987 }
>> 988 print "};\n.br\n";
681 989
682 ($args{'parameterdescs'}{$parameter_na !! 990 print ".SH Arguments\n";
683 print ".IP \"" . $parameter . "\" 12\n !! 991 foreach $parameter (@{$args{'parameterlist'}}) {
684 output_highlight($args{'parameterdescs !! 992 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
>> 993 print ".IP \"".$parameter."\" 12\n";
>> 994 output_highlight($args{'parameterdescs'}{$parameter});
685 } 995 }
686 foreach $section (@{$args{'sectionlist'}}) 996 foreach $section (@{$args{'sectionlist'}}) {
687 print ".SH \"$section\"\n"; !! 997 print ".SH \"$section\"\n";
688 output_highlight($args{'sections'}{$se !! 998 output_highlight($args{'sections'}{$section});
689 } 999 }
690 } 1000 }
691 1001
692 ## 1002 ##
693 # output typedef in man 1003 # output typedef in man
694 sub output_typedef_man(%) { 1004 sub output_typedef_man(%) {
695 my %args = %{$_[0]}; 1005 my %args = %{$_[0]};
696 my ($parameter, $section); 1006 my ($parameter, $section);
697 1007
698 print ".TH \"$args{'module'}\" 9 \"$args{' 1008 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
699 1009
700 print ".SH NAME\n"; 1010 print ".SH NAME\n";
701 print "typedef " . $args{'typedef'} . " \\ !! 1011 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
702 1012
703 foreach $section (@{$args{'sectionlist'}}) 1013 foreach $section (@{$args{'sectionlist'}}) {
704 print ".SH \"$section\"\n"; !! 1014 print ".SH \"$section\"\n";
705 output_highlight($args{'sections'}{$se !! 1015 output_highlight($args{'sections'}{$section});
706 } 1016 }
707 } 1017 }
708 1018
709 sub output_blockhead_man(%) { !! 1019 sub output_intro_man(%) {
710 my %args = %{$_[0]}; 1020 my %args = %{$_[0]};
711 my ($parameter, $section); 1021 my ($parameter, $section);
712 my $count; 1022 my $count;
713 1023
714 print ".TH \"$args{'module'}\" 9 \"$args{' 1024 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
715 1025
716 foreach $section (@{$args{'sectionlist'}}) 1026 foreach $section (@{$args{'sectionlist'}}) {
717 print ".SH \"$section\"\n"; !! 1027 print ".SH \"$section\"\n";
718 output_highlight($args{'sections'}{$se !! 1028 output_highlight($args{'sections'}{$section});
719 } 1029 }
720 } 1030 }
721 1031
722 ## 1032 ##
723 # output in restructured text !! 1033 # output in text
724 # !! 1034 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]}; <<
733 my ($parameter, $section); <<
734 <<
735 foreach $section (@{$args{'sectionlist'}}) <<
736 next if (defined($nosymbol_table{$sect <<
737 <<
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]}; 1035 my %args = %{$_[0]};
821 my ($parameter, $section); 1036 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 1037
>> 1038 print "Function:\n\n";
>> 1039 my $start=$args{'functiontype'}." ".$args{'function'}." (";
>> 1040 print $start;
831 my $count = 0; 1041 my $count = 0;
832 foreach my $parameter (@{$args{'parameterl 1042 foreach my $parameter (@{$args{'parameterlist'}}) {
833 if ($count ne 0) { !! 1043 $type = $args{'parametertypes'}{$parameter};
834 $signature .= ", "; !! 1044 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
835 } !! 1045 # pointer-to-function
836 $count++; !! 1046 print $1.$parameter.") (".$2;
837 $type = $args{'parametertypes'}{$param !! 1047 } else {
838 !! 1048 print $type." ".$parameter;
839 if ($type =~ m/$function_pointer/) { !! 1049 }
840 # pointer-to-function !! 1050 if ($count != $#{$args{'parameterlist'}}) {
841 $signature .= $1 . $parameter . ") !! 1051 $count++;
842 } else { !! 1052 print ",\n";
843 $signature .= $type; !! 1053 print " " x length($start);
844 } !! 1054 } else {
845 } !! 1055 print ");\n\n";
846 !! 1056 }
847 $signature .= ")"; <<
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 } 1057 }
879 1058
880 if (!$args{'typedef'}) { !! 1059 print "Arguments:\n\n";
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 1060 foreach $parameter (@{$args{'parameterlist'}}) {
895 my $parameter_name = $parameter; !! 1061 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 } 1062 }
917 !! 1063 output_section_text(@_);
918 output_section_rst(@_); <<
919 $lineprefix = $oldprefix; <<
920 } 1064 }
921 1065
922 sub output_section_rst(%) { !! 1066 #output sections in text
>> 1067 sub output_section_text(%) {
923 my %args = %{$_[0]}; 1068 my %args = %{$_[0]};
924 my $section; 1069 my $section;
925 my $oldprefix = $lineprefix; <<
926 1070
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"; 1071 print "\n";
>> 1072 foreach $section (@{$args{'sectionlist'}}) {
>> 1073 print "$section:\n\n";
>> 1074 output_highlight($args{'sections'}{$section});
>> 1075 }
>> 1076 print "\n\n";
934 } 1077 }
935 1078
936 sub output_enum_rst(%) { !! 1079 # output enum in text
>> 1080 sub output_enum_text(%) {
937 my %args = %{$_[0]}; 1081 my %args = %{$_[0]};
938 my ($parameter); 1082 my ($parameter);
939 my $oldprefix = $lineprefix; <<
940 my $count; 1083 my $count;
941 my $outer; !! 1084 print "Enum:\n\n";
942 1085
943 if ($sphinx_major < 3) { !! 1086 print "enum ".$args{'enum'}." {\n";
944 my $name = "enum " . $args{'enum'}; !! 1087 $count = 0;
945 print "\n\n.. c:type:: " . $name . "\n !! 1088 foreach $parameter (@{$args{'parameterlist'}}) {
946 } else { !! 1089 print "\t$parameter";
947 my $name = $args{'enum'}; !! 1090 if ($count != $#{$args{'parameterlist'}}) {
948 print "\n\n.. c:enum:: " . $name . "\n !! 1091 $count++;
>> 1092 print ",";
>> 1093 }
>> 1094 print "\n";
949 } 1095 }
950 print_lineno($declaration_start_line); !! 1096 print "};\n\n";
951 $lineprefix = " "; <<
952 output_highlight_rst($args{'purpose'}); <<
953 print "\n"; <<
954 1097
955 print ".. container:: kernelindent\n\n"; !! 1098 print "Constants:\n\n";
956 $outer = $lineprefix . " "; <<
957 $lineprefix = $outer . " "; <<
958 print $outer . "**Constants**\n\n"; <<
959 foreach $parameter (@{$args{'parameterlist 1099 foreach $parameter (@{$args{'parameterlist'}}) {
960 print $outer . "``$parameter``\n"; !! 1100 print "$parameter\n\t";
961 !! 1101 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 } 1102 }
969 print "\n"; !! 1103
970 $lineprefix = $oldprefix; !! 1104 output_section_text(@_);
971 output_section_rst(@_); <<
972 } 1105 }
973 1106
974 sub output_typedef_rst(%) { !! 1107 # output typedef in text
>> 1108 sub output_typedef_text(%) {
975 my %args = %{$_[0]}; 1109 my %args = %{$_[0]};
976 my ($parameter); 1110 my ($parameter);
977 my $oldprefix = $lineprefix; !! 1111 my $count;
978 my $name; !! 1112 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 1113
991 $lineprefix = $oldprefix; !! 1114 print "typedef ".$args{'typedef'}."\n";
992 output_section_rst(@_); !! 1115 output_section_text(@_);
993 } 1116 }
994 1117
995 sub output_struct_rst(%) { !! 1118 # output struct as text
>> 1119 sub output_struct_text(%) {
996 my %args = %{$_[0]}; 1120 my %args = %{$_[0]};
997 my ($parameter); 1121 my ($parameter);
998 my $oldprefix = $lineprefix; <<
999 1122
1000 if ($sphinx_major < 3) { !! 1123 print $args{'type'}." ".$args{'struct'}.":\n\n";
1001 my $name = $args{'type'} . " " . $arg !! 1124 print $args{'type'}." ".$args{'struct'}." {\n";
1002 print "\n\n.. c:type:: " . $name . "\ !! 1125 foreach $parameter (@{$args{'parameterlist'}}) {
1003 } else { !! 1126 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1004 my $name = $args{'struct'}; !! 1127 $type = $args{'parametertypes'}{$parameter};
1005 if ($args{'type'} eq 'union') { !! 1128 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1006 print "\n\n.. c:union:: " . $name !! 1129 # pointer-to-function
1007 } else { !! 1130 print "\t$1 $parameter) ($2);\n";
1008 print "\n\n.. c:struct:: " . $nam !! 1131 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1009 } !! 1132 print "\t$1 $parameter$2;\n";
>> 1133 } else {
>> 1134 print "\t".$type." ".$parameter.";\n";
>> 1135 }
1010 } 1136 }
1011 print_lineno($declaration_start_line); !! 1137 print "};\n\n";
1012 $lineprefix = " "; <<
1013 output_highlight_rst($args{'purpose'}); <<
1014 print "\n"; <<
1015 1138
1016 print ".. container:: kernelindent\n\n"; !! 1139 print "Members:\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 <<
1023 $lineprefix = " "; <<
1024 print $lineprefix . "**Members**\n\n"; <<
1025 foreach $parameter (@{$args{'parameterlis 1140 foreach $parameter (@{$args{'parameterlist'}}) {
1026 ($parameter =~ /^#/) && next; !! 1141 ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1027 !! 1142 print "$parameter\n\t";
1028 my $parameter_name = $parameter; !! 1143 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 } 1144 }
1040 print "\n"; 1145 print "\n";
1041 !! 1146 output_section_text(@_);
1042 $lineprefix = $oldprefix; <<
1043 output_section_rst(@_); <<
1044 } <<
1045 <<
1046 ## none mode output functions <<
1047 <<
1048 sub output_function_none(%) { <<
1049 } 1147 }
1050 1148
1051 sub output_enum_none(%) { !! 1149 sub output_intro_text(%) {
1052 } !! 1150 my %args = %{$_[0]};
1053 !! 1151 my ($parameter, $section);
1054 sub output_typedef_none(%) { <<
1055 } <<
1056 <<
1057 sub output_struct_none(%) { <<
1058 } <<
1059 1152
1060 sub output_blockhead_none(%) { !! 1153 foreach $section (@{$args{'sectionlist'}}) {
>> 1154 print " $section:\n";
>> 1155 print " -> ";
>> 1156 output_highlight($args{'sections'}{$section});
>> 1157 }
1061 } 1158 }
1062 1159
1063 ## 1160 ##
1064 # generic output function for all types (func !! 1161 # generic output function for typedefs
1065 # calls the generated, variable output_ funct <<
1066 # functype and output_mode <<
1067 sub output_declaration { 1162 sub output_declaration {
1068 no strict 'refs'; 1163 no strict 'refs';
1069 my $name = shift; 1164 my $name = shift;
1070 my $functype = shift; 1165 my $functype = shift;
1071 my $func = "output_${functype}_$output_mo 1166 my $func = "output_${functype}_$output_mode";
1072 !! 1167 if (($function_only==0) ||
1073 return if (defined($nosymbol_table{$name} !! 1168 ( $function_only == 1 && defined($function_table{$name})) ||
1074 !! 1169 ( $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 { 1170 {
1082 &$func(@_); 1171 &$func(@_);
1083 $section_counter++; !! 1172 $section_counter++;
1084 } 1173 }
1085 } 1174 }
1086 1175
1087 ## 1176 ##
1088 # generic output function - calls the right o !! 1177 # generic output function - calls the right one based
1089 sub output_blockhead { !! 1178 # on current output mode.
>> 1179 sub output_intro {
1090 no strict 'refs'; 1180 no strict 'refs';
1091 my $func = "output_blockhead_" . $output_ !! 1181 my $func = "output_intro_".$output_mode;
1092 &$func(@_); 1182 &$func(@_);
1093 $section_counter++; 1183 $section_counter++;
1094 } 1184 }
1095 1185
1096 ## 1186 ##
1097 # takes a declaration (struct, union, enum, t !! 1187 # takes a declaration (struct, union, enum, typedef) and
1098 # invokes the right handler. NOT called for f 1188 # invokes the right handler. NOT called for functions.
1099 sub dump_declaration($$) { 1189 sub dump_declaration($$) {
1100 no strict 'refs'; 1190 no strict 'refs';
1101 my ($prototype, $file) = @_; 1191 my ($prototype, $file) = @_;
1102 my $func = "dump_" . $decl_type; !! 1192 my $func = "dump_".$decl_type;
1103 &$func(@_); 1193 &$func(@_);
1104 } 1194 }
1105 1195
1106 sub dump_union($$) { 1196 sub dump_union($$) {
1107 dump_struct(@_); 1197 dump_struct(@_);
1108 } 1198 }
1109 1199
1110 sub dump_struct($$) { 1200 sub dump_struct($$) {
1111 my $x = shift; 1201 my $x = shift;
1112 my $file = shift; 1202 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 1203
1121 if ($x =~ /($type)\s+(\w+)\s*$definition_ !! 1204 if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1122 $decl_type = $1; <<
1123 $declaration_name = $2; 1205 $declaration_name = $2;
1124 $members = $3; !! 1206 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 1207
1290 sub show_warnings($$) { !! 1208 # ignore embedded structs or unions
1291 my $functype = shift; !! 1209 $members =~ s/{.*}//g;
1292 my $name = shift; <<
1293 <<
1294 return 0 if (defined($nosymbol_table{$nam <<
1295 1210
1296 return 1 if ($output_selection == OUTPUT_ !! 1211 create_parameterlist($members, ';', $file);
1297 1212
1298 if ($output_selection == OUTPUT_EXPORTED) !! 1213 output_declaration($declaration_name,
1299 if (defined($function_table{$name})) !! 1214 'struct',
1300 return 1; !! 1215 {'struct' => $declaration_name,
1301 } else { !! 1216 'module' => $modulename,
1302 return 0; !! 1217 'parameterlist' => \@parameterlist,
1303 } !! 1218 'parameterdescs' => \%parameterdescs,
1304 } !! 1219 'parametertypes' => \%parametertypes,
1305 if ($output_selection == OUTPUT_INTERNAL) !! 1220 'sectionlist' => \@sectionlist,
1306 if (!($functype eq "function" && defi !! 1221 'sections' => \%sections,
1307 return 1; !! 1222 'purpose' => $declaration_purpose,
1308 } else { !! 1223 'type' => $decl_type
1309 return 0; !! 1224 });
1310 } !! 1225 }
1311 } !! 1226 else {
1312 if ($output_selection == OUTPUT_INCLUDE) !! 1227 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1313 if (defined($function_table{$name})) !! 1228 ++$errors;
1314 return 1; <<
1315 } else { <<
1316 return 0; <<
1317 } <<
1318 } 1229 }
1319 die("Please add the new output type at sh <<
1320 } 1230 }
1321 1231
1322 sub dump_enum($$) { 1232 sub dump_enum($$) {
1323 my $x = shift; 1233 my $x = shift;
1324 my $file = shift; 1234 my $file = shift;
1325 my $members; <<
1326 1235
1327 # ignore members marked private: !! 1236 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
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 <<
1335 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\ <<
1336 $declaration_name = $2; <<
1337 $members = $1; <<
1338 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) <<
1339 $declaration_name = $1; 1237 $declaration_name = $1;
1340 $members = $2; !! 1238 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 <<
1354 my %_members; <<
1355 <<
1356 $members =~ s/\s+$//; <<
1357 $members =~ s/\([^;]*?[\)]//g; <<
1358 <<
1359 foreach my $arg (split ',', $members) <<
1360 $arg =~ s/^\s*(\w+).*/$1/; <<
1361 push @parameterlist, $arg; <<
1362 if (!$parameterdescs{$arg}) { <<
1363 $parameterdescs{$arg} = $unde <<
1364 if (show_warnings("enum", $de <<
1365 emit_warning("${file}:$." <<
1366 } <<
1367 } <<
1368 $_members{$arg} = 1; <<
1369 } <<
1370 1239
1371 while (my ($k, $v) = each %parameterd !! 1240 foreach my $arg (split ',', $members) {
1372 if (!exists($_members{$k})) { !! 1241 $arg =~ s/^\s*(\w+).*/$1/;
1373 if (show_warnings("enum", $de !! 1242 push @parameterlist, $arg;
1374 emit_warning("${file}:$." !! 1243 if (!$parameterdescs{$arg}) {
1375 } !! 1244 $parameterdescs{$arg} = $undescribed;
1376 } !! 1245 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1377 } !! 1246 "not described in enum '$declaration_name'\n";
1378 !! 1247 }
1379 output_declaration($declaration_name, !! 1248
1380 'enum', !! 1249 }
1381 {'enum' => $declar !! 1250
1382 'module' => $modu !! 1251 output_declaration($declaration_name,
1383 'parameterlist' = !! 1252 'enum',
1384 'parameterdescs' !! 1253 {'enum' => $declaration_name,
1385 'sectionlist' => !! 1254 'module' => $modulename,
1386 'sections' => \%s !! 1255 'parameterlist' => \@parameterlist,
1387 'purpose' => $dec !! 1256 'parameterdescs' => \%parameterdescs,
1388 }); !! 1257 'sectionlist' => \@sectionlist,
1389 } else { !! 1258 'sections' => \%sections,
1390 print STDERR "${file}:$.: error: Cann !! 1259 'purpose' => $declaration_purpose
1391 ++$errors; !! 1260 });
>> 1261 }
>> 1262 else {
>> 1263 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
>> 1264 ++$errors;
1392 } 1265 }
1393 } 1266 }
1394 1267
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($$) { 1268 sub dump_typedef($$) {
1403 my $x = shift; 1269 my $x = shift;
1404 my $file = shift; 1270 my $file = shift;
1405 1271
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 =~ /\ 1272 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1439 $x =~ s/\(*.\)\s*;$/;/; 1273 $x =~ s/\(*.\)\s*;$/;/;
1440 $x =~ s/\[*.\]\s*;$/;/; !! 1274 $x =~ s/\[*.\]\s*;$/;/;
1441 } 1275 }
1442 1276
1443 if ($x =~ /typedef.*\s+(\w+)\s*;/) { 1277 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1444 $declaration_name = $1; 1278 $declaration_name = $1;
1445 1279
1446 if ($identifier ne $declaration_name) !! 1280 output_declaration($declaration_name,
1447 emit_warning("${file}:$.", "expec !! 1281 'typedef',
1448 return; !! 1282 {'typedef' => $declaration_name,
1449 } !! 1283 'module' => $modulename,
1450 !! 1284 'sectionlist' => \@sectionlist,
1451 output_declaration($declaration_name, !! 1285 'sections' => \%sections,
1452 'typedef', !! 1286 'purpose' => $declaration_purpose
1453 {'typedef' => $dec !! 1287 });
1454 'module' => $modu !! 1288 }
1455 'sectionlist' => !! 1289 else {
1456 'sections' => \%s !! 1290 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1457 'purpose' => $dec !! 1291 ++$errors;
1458 }); <<
1459 } else { <<
1460 print STDERR "${file}:$.: error: Cann <<
1461 ++$errors; <<
1462 } 1292 }
1463 } 1293 }
1464 1294
1465 sub save_struct_actual($) { !! 1295 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; 1296 my $args = shift;
1475 my $splitter = shift; 1297 my $splitter = shift;
1476 my $file = shift; 1298 my $file = shift;
1477 my $declaration_name = shift; <<
1478 my $type; 1299 my $type;
1479 my $param; 1300 my $param;
1480 1301
1481 # temporarily replace commas inside funct !! 1302 while ($args =~ /(\([^\),]+),/) {
1482 my $arg_expr = qr{\([^\),]+}; !! 1303 $args =~ s/(\([^\),]+),/$1#/g;
1483 while ($args =~ /$arg_expr,/) { <<
1484 $args =~ s/($arg_expr),/$1#/g; <<
1485 } 1304 }
1486 !! 1305
1487 foreach my $arg (split($splitter, $args)) 1306 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 1307 # strip leading/trailing spaces
1493 $arg =~ s/^\s*//; 1308 $arg =~ s/^\s*//;
1494 $arg =~ s/\s*$//; !! 1309 $arg =~ s/\s*$//;
1495 $arg =~ s/\s+/ /; !! 1310 $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 <<
1538 unshift(@args, pop @first_arg); <<
1539 $type = join " ", @first_arg; <<
1540 <<
1541 foreach $param (@args) { <<
1542 if ($param =~ m/^(\*+)\s*(.*) <<
1543 save_struct_actual($2); <<
1544 <<
1545 push_parameter($2, "$type <<
1546 } elsif ($param =~ m/(.*?):(\ <<
1547 if ($type ne "") { # skip <<
1548 save_struct_actual($1 <<
1549 push_parameter($1, "$ <<
1550 } <<
1551 } else { <<
1552 save_struct_actual($param <<
1553 push_parameter($param, $t <<
1554 } <<
1555 } <<
1556 } <<
1557 } <<
1558 } <<
1559 <<
1560 sub push_parameter($$$$$) { <<
1561 my $param = shift; <<
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 1311
1607 # warn if parameter has no description !! 1312 if ($arg =~ m/\(/) {
1608 # (but ignore ones starting with # as the !! 1313 # pointer-to-function
1609 # but inline preprocessor statements); !! 1314 $arg =~ tr/#/,/;
1610 # Note: It will also ignore void params a !! 1315 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
1611 if (!defined $parameterdescs{$param} && $ !! 1316 $param = $1;
1612 $parameterdescs{$param} = $undescribe !! 1317 $type = $arg;
1613 !! 1318 $type =~ s/([^\(]+\(\*)$param/$1/;
1614 if (show_warnings($type, $declaration !! 1319 } else {
1615 emit_warning("${file}:$.", "Funct !! 1320 # evil magic to get fixed array parameters to work
>> 1321 $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/;
>> 1322 my @args = split('\s', $arg);
>> 1323
>> 1324 $param = pop @args;
>> 1325 if ($param =~ m/^(\*+)(.*)/) {
>> 1326 $param = $2;
>> 1327 push @args, $1;
>> 1328 }
>> 1329 elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) {
>> 1330 $param = $1;
>> 1331 push @args, ":$2";
>> 1332 }
>> 1333 $type = join " ", @args;
>> 1334 }
>> 1335
>> 1336 if ($type eq "" && $param eq "...")
>> 1337 {
>> 1338 $type="...";
>> 1339 $param="...";
>> 1340 $parameterdescs{"..."} = "variable arguments";
>> 1341 }
>> 1342 elsif ($type eq "" && ($param eq "" or $param eq "void"))
>> 1343 {
>> 1344 $type="";
>> 1345 $param="void";
>> 1346 $parameterdescs{void} = "no arguments";
>> 1347 }
>> 1348 if (defined $type && $type && !defined $parameterdescs{$param}) {
>> 1349 $parameterdescs{$param} = $undescribed;
>> 1350
>> 1351 if (($type eq 'function') || ($type eq 'enum')) {
>> 1352 print STDERR "Warning(${file}:$.): Function parameter ".
>> 1353 "or member '$param' not " .
>> 1354 "described in '$declaration_name'\n";
>> 1355 }
>> 1356 print STDERR "Warning(${file}:$.):".
>> 1357 " No description found for parameter '$param'\n";
>> 1358 ++$warnings;
1616 } 1359 }
1617 } <<
1618 1360
1619 # strip spaces from $param so that it is !! 1361 push @parameterlist, $param;
1620 # on @parameterlist; !! 1362 $parametertypes{$param} = $type;
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 } 1363 }
1698 } 1364 }
1699 1365
1700 ## 1366 ##
1701 # takes a function prototype and the name of 1367 # takes a function prototype and the name of the current file being
1702 # processed and spits out all the details sto 1368 # processed and spits out all the details stored in the global
1703 # arrays/hashes. 1369 # arrays/hashes.
1704 sub dump_function($$) { 1370 sub dump_function($$) {
1705 my $prototype = shift; 1371 my $prototype = shift;
1706 my $file = shift; 1372 my $file = shift;
1707 my $noret = 0; <<
1708 <<
1709 print_lineno($new_start_line); <<
1710 1373
1711 $prototype =~ s/^static +//; 1374 $prototype =~ s/^static +//;
1712 $prototype =~ s/^extern +//; 1375 $prototype =~ s/^extern +//;
1713 $prototype =~ s/^asmlinkage +//; <<
1714 $prototype =~ s/^inline +//; 1376 $prototype =~ s/^inline +//;
1715 $prototype =~ s/^__inline__ +//; 1377 $prototype =~ s/^__inline__ +//;
1716 $prototype =~ s/^__inline +//; !! 1378 $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 1379
1743 # Yes, this truly is vile. We are lookin 1380 # Yes, this truly is vile. We are looking for:
1744 # 1. Return type (may be nothing if we're 1381 # 1. Return type (may be nothing if we're looking at a macro)
1745 # 2. Function name 1382 # 2. Function name
1746 # 3. Function parameters. 1383 # 3. Function parameters.
1747 # 1384 #
1748 # All the while we have to watch out for 1385 # All the while we have to watch out for function pointer parameters
1749 # (which IIRC is what the two sections ar 1386 # (which IIRC is what the two sections are for), C types (these
1750 # regexps don't even start to express all 1387 # regexps don't even start to express all the possibilities), and
1751 # so on. 1388 # so on.
1752 # 1389 #
1753 # If you mess with these regexps, it's a 1390 # If you mess with these regexps, it's a good idea to check that
1754 # the following functions' documentation 1391 # the following functions' documentation still comes out right:
1755 # - parport_register_device (function poi 1392 # - parport_register_device (function pointer parameters)
1756 # - atomic_set (macro) 1393 # - atomic_set (macro)
1757 # - pci_match_device, __copy_to_user (lon !! 1394 # - 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 1395
1780 create_parameterlist($args, ',', $fil !! 1396 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1781 } else { !! 1397 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1782 emit_warning("${file}:$.", "cannot un !! 1398 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1783 return; !! 1399 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1784 } !! 1400 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1401 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1402 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1403 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1404 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1405 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1406 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1407 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1408 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1409 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
>> 1410 $return_type = $1;
>> 1411 $declaration_name = $2;
>> 1412 my $args = $3;
1785 1413
1786 if ($identifier ne $declaration_name) { !! 1414 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 { 1415 } else {
1820 output_declaration($declaration_name, !! 1416 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1821 'function', !! 1417 ++$errors;
1822 {'function' => $de !! 1418 return;
1823 'module' => $modu !! 1419 }
1824 'functiontype' => !! 1420
1825 'parameterlist' = !! 1421 output_declaration($declaration_name,
1826 'parameterdescs' !! 1422 'function',
1827 'parametertypes' !! 1423 {'function' => $declaration_name,
1828 'sectionlist' => !! 1424 'module' => $modulename,
1829 'sections' => \%s !! 1425 'functiontype' => $return_type,
1830 'purpose' => $dec !! 1426 'parameterlist' => \@parameterlist,
1831 }); !! 1427 'parameterdescs' => \%parameterdescs,
1832 } !! 1428 'parametertypes' => \%parametertypes,
>> 1429 'sectionlist' => \@sectionlist,
>> 1430 'sections' => \%sections,
>> 1431 'purpose' => $declaration_purpose
>> 1432 });
>> 1433 }
>> 1434
>> 1435 sub process_file($);
>> 1436
>> 1437 # Read the file that maps relative names to absolute names for
>> 1438 # separate source and object directories and for shadow trees.
>> 1439 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
>> 1440 my ($relname, $absname);
>> 1441 while(<SOURCE_MAP>) {
>> 1442 chop();
>> 1443 ($relname, $absname) = (split())[0..1];
>> 1444 $relname =~ s:^/+::;
>> 1445 $source_map{$relname} = $absname;
>> 1446 }
>> 1447 close(SOURCE_MAP);
>> 1448 }
>> 1449
>> 1450 if ($filelist) {
>> 1451 open(FLIST,"<$filelist") or die "Can't open file list $filelist";
>> 1452 while(<FLIST>) {
>> 1453 chop;
>> 1454 process_file($_);
>> 1455 }
>> 1456 }
>> 1457
>> 1458 foreach (@ARGV) {
>> 1459 chomp;
>> 1460 process_file($_);
>> 1461 }
>> 1462 if ($verbose && $errors) {
>> 1463 print STDERR "$errors errors\n";
>> 1464 }
>> 1465 if ($verbose && $warnings) {
>> 1466 print STDERR "$warnings warnings\n";
1833 } 1467 }
1834 1468
>> 1469 exit($errors);
>> 1470
1835 sub reset_state { 1471 sub reset_state {
1836 $function = ""; 1472 $function = "";
>> 1473 %constants = ();
1837 %parameterdescs = (); 1474 %parameterdescs = ();
1838 %parametertypes = (); 1475 %parametertypes = ();
1839 @parameterlist = (); 1476 @parameterlist = ();
1840 %sections = (); 1477 %sections = ();
1841 @sectionlist = (); 1478 @sectionlist = ();
1842 $sectcheck = ""; <<
1843 $struct_actual = ""; <<
1844 $prototype = ""; 1479 $prototype = "";
1845 !! 1480
1846 $state = STATE_NORMAL; !! 1481 $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 } 1482 }
1876 1483
1877 sub syscall_munge() { !! 1484 sub process_state3_function($$) {
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 } <<
1910 <<
1911 sub process_proto_function($$) { <<
1912 my $x = shift; 1485 my $x = shift;
1913 my $file = shift; 1486 my $file = shift;
1914 1487
1915 $x =~ s@\/\/.*$@@gos; # strip C99-style c !! 1488 if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
1916 !! 1489 # do nothing
1917 if ($x =~ /^#/ && $x !~ /^#\s*define/) { !! 1490 }
1918 # do nothing !! 1491 elsif ($x =~ /([^\{]*)/) {
1919 } elsif ($x =~ /([^\{]*)/) { <<
1920 $prototype .= $1; 1492 $prototype .= $1;
1921 } 1493 }
1922 !! 1494 if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) {
1923 if (($x =~ /\{/) || ($x =~ /\#\s*define/) !! 1495 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1924 $prototype =~ s@/\*.*?\*/@@gos; !! 1496 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1925 $prototype =~ s@[\r\n]+@ @gos; # stri !! 1497 $prototype =~ s@^\s+@@gos; # strip leading spaces
1926 $prototype =~ s@^\s+@@gos; # strip le !! 1498 dump_function($prototype,$file);
1927 !! 1499 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 } 1500 }
1943 } 1501 }
1944 1502
1945 sub process_proto_type($$) { !! 1503 sub process_state3_type($$) {
1946 my $x = shift; 1504 my $x = shift;
1947 my $file = shift; 1505 my $file = shift;
1948 1506
>> 1507 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1949 $x =~ s@[\r\n]+@ @gos; # strip newlines/c 1508 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1950 $x =~ s@^\s+@@gos; # strip leading spaces 1509 $x =~ s@^\s+@@gos; # strip leading spaces
1951 $x =~ s@\s+$@@gos; # strip trailing space 1510 $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 1511
1959 while (1) { 1512 while (1) {
1960 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ !! 1513 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1961 if( length $prototype ) { !! 1514 $prototype .= $1 . $2;
1962 $prototype .= " " !! 1515 ($2 eq '{') && $brcount++;
1963 } !! 1516 ($2 eq '}') && $brcount--;
1964 $prototype .= $1 . $2; !! 1517 if (($2 eq ';') && ($brcount == 0)) {
1965 ($2 eq '{') && $brcount++; !! 1518 dump_declaration($prototype,$file);
1966 ($2 eq '}') && $brcount--; !! 1519 reset_state();
1967 if (($2 eq ';') && ($brcount == 0 !! 1520 last;
1968 dump_declaration($prototype, !! 1521 }
1969 reset_state(); !! 1522 $x = $3;
1970 last; !! 1523 } else {
1971 } !! 1524 $prototype .= $x;
1972 $x = $3; !! 1525 last;
1973 } else { !! 1526 }
1974 $prototype .= $x; <<
1975 last; <<
1976 } <<
1977 } 1527 }
1978 } 1528 }
1979 1529
1980 !! 1530 sub process_file($) {
1981 sub map_filename($) { !! 1531 my ($file) = @_;
1982 my $file; !! 1532 my $identifier;
1983 my ($orig_file) = @_; !! 1533 my $func;
1984 !! 1534 my $initial_section_counter = $section_counter;
1985 if (defined($ENV{'SRCTREE'})) { <<
1986 $file = "$ENV{'SRCTREE'}" . "/" . $or <<
1987 } else { <<
1988 $file = $orig_file; <<
1989 } <<
1990 1535
1991 if (defined($source_map{$file})) { 1536 if (defined($source_map{$file})) {
1992 $file = $source_map{$file}; !! 1537 $file = $source_map{$file};
1993 } 1538 }
1994 1539
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")) { 1540 if (!open(IN,"<$file")) {
2003 print STDERR "Error: Cannot open file !! 1541 print STDERR "Error: Cannot open file $file\n";
2004 ++$errors; !! 1542 ++$errors;
2005 return; !! 1543 return;
2006 } 1544 }
2007 1545
>> 1546 $section_counter = 0;
2008 while (<IN>) { 1547 while (<IN>) {
2009 if (/$export_symbol/) { !! 1548 if ($state == 0) {
2010 next if (defined($nosymbol_table{ !! 1549 if (/$doc_start/o) {
2011 $function_table{$2} = 1; !! 1550 $state = 1; # next line is always the function name
2012 } !! 1551 }
2013 if (/$export_symbol_ns/) { !! 1552 } elsif ($state == 1) { # this line is the function name (always)
2014 next if (defined($nosymbol_table{ !! 1553 if (/$doc_block/o) {
2015 $function_table{$2} = 1; !! 1554 $state = 4;
2016 } !! 1555 $contents = "";
2017 } !! 1556 if ( $1 eq "" ) {
2018 !! 1557 $section = $section_intro;
2019 close(IN); !! 1558 } else {
2020 } !! 1559 $section = $1;
2021 !! 1560 }
2022 # !! 1561 }
2023 # Parsers for the various processing states. !! 1562 elsif (/$doc_decl/o) {
2024 # !! 1563 $identifier = $1;
2025 # STATE_NORMAL: looking for the /** to begin !! 1564 if (/\s*([\w\s]+?)\s*-/) {
2026 # !! 1565 $identifier = $1;
2027 sub process_normal() { !! 1566 }
2028 if (/$doc_start/o) { !! 1567
2029 $state = STATE_NAME; # next li !! 1568 $state = 2;
2030 $in_doc_sect = 0; !! 1569 if (/-(.*)/) {
2031 $declaration_start_line = $. + 1; !! 1570 $declaration_purpose = $1;
2032 } !! 1571 } else {
2033 } !! 1572 $declaration_purpose = "";
2034 !! 1573 }
2035 # !! 1574 if ($identifier =~ m/^struct/) {
2036 # STATE_NAME: Looking for the "name - descrip !! 1575 $decl_type = 'struct';
2037 # !! 1576 } elsif ($identifier =~ m/^union/) {
2038 sub process_name($$) { !! 1577 $decl_type = 'union';
2039 my $file = shift; !! 1578 } elsif ($identifier =~ m/^enum/) {
2040 my $descr; !! 1579 $decl_type = 'enum';
2041 !! 1580 } elsif ($identifier =~ m/^typedef/) {
2042 if (/$doc_block/o) { !! 1581 $decl_type = 'typedef';
2043 $state = STATE_DOCBLOCK; !! 1582 } else {
2044 $contents = ""; !! 1583 $decl_type = 'function';
2045 $new_start_line = $.; !! 1584 }
2046 !! 1585
2047 if ( $1 eq "" ) { !! 1586 if ($verbose) {
2048 $section = $section_intro; !! 1587 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
2049 } else { !! 1588 }
2050 $section = $1; !! 1589 } else {
2051 } !! 1590 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
2052 } elsif (/$doc_decl/o) { !! 1591 " - I thought it was a doc line\n";
2053 $identifier = $1; !! 1592 ++$warnings;
2054 my $is_kernel_comment = 0; !! 1593 $state = 0;
2055 my $decl_start = qr{$doc_com}; !! 1594 }
2056 # test for pointer declaration type, !! 1595 } elsif ($state == 2) { # look for head: lines, and include content
2057 my $fn_type = qr{\w+\s*\*\s*}; !! 1596 if (/$doc_sect/o) {
2058 my $parenthesis = qr{\(\w*\)}; !! 1597 $newsection = $1;
2059 my $decl_end = qr{[-:].*}; !! 1598 $newcontents = $2;
2060 if (/^$decl_start([\w\s]+?)$parenthes !! 1599
2061 $identifier = $1; !! 1600 if ($contents ne "") {
2062 } !! 1601 $contents =~ s/\&/\\\\\\amp;/g;
2063 if ($identifier =~ m/^(struct|union|e !! 1602 $contents =~ s/\</\\\\\\lt;/g;
2064 $decl_type = $1; !! 1603 $contents =~ s/\>/\\\\\\gt;/g;
2065 $identifier = $2; !! 1604 dump_section($section, $contents);
2066 $is_kernel_comment = 1; !! 1605 $section = $section_default;
2067 } !! 1606 }
2068 # Look for foo() or static void foo() !! 1607
2069 # identifier !! 1608 $contents = $newcontents;
2070 elsif (/^$decl_start$fn_type?(\w+)\s* !! 1609 if ($contents ne "") {
2071 /^$decl_start$fn_type?(\w+.*)$par !! 1610 $contents .= "\n";
2072 $identifier = $1; !! 1611 }
2073 $decl_type = 'function'; !! 1612 $section = $newsection;
2074 $identifier =~ s/^define\s+//; !! 1613 } elsif (/$doc_end/) {
2075 $is_kernel_comment = 1; !! 1614
2076 } !! 1615 if ($contents ne "") {
2077 $identifier =~ s/\s+$//; !! 1616 $contents =~ s/\&/\\\\\\amp;/g;
2078 !! 1617 $contents =~ s/\</\\\\\\lt;/g;
2079 $state = STATE_BODY; !! 1618 $contents =~ s/\>/\\\\\\gt;/g;
2080 # if there's no @param blocks need to !! 1619 dump_section($section, $contents);
2081 # here !! 1620 $section = $section_default;
2082 $contents = ""; !! 1621 $contents = "";
2083 $section = $section_default; !! 1622 }
2084 $new_start_line = $. + 1; !! 1623
2085 if (/[-:](.*)/) { !! 1624 $prototype = "";
2086 # strip leading/trailing/multiple !! 1625 $state = 3;
2087 $descr= $1; !! 1626 $brcount = 0;
2088 $descr =~ s/^\s*//; !! 1627 # print STDERR "end of doc comment, looking for prototype\n";
2089 $descr =~ s/\s*$//; !! 1628 } elsif (/$doc_content/) {
2090 $descr =~ s/\s+/ /g; !! 1629 # miguel-style comment kludge, look for blank lines after
2091 $declaration_purpose = $descr; !! 1630 # @parameter line to signify start of description
2092 $state = STATE_BODY_MAYBE; !! 1631 if ($1 eq "" &&
2093 } else { !! 1632 ($section =~ m/^@/ || $section eq $section_context)) {
2094 $declaration_purpose = ""; !! 1633 $contents =~ s/\&/\\\\\\amp;/g;
2095 } !! 1634 $contents =~ s/\</\\\\\\lt;/g;
2096 !! 1635 $contents =~ s/\>/\\\\\\gt;/g;
2097 if (!$is_kernel_comment) { !! 1636 dump_section($section, $contents);
2098 emit_warning("${file}:$.", "This !! 1637 $section = $section_default;
2099 $state = STATE_NORMAL; !! 1638 $contents = "";
2100 } !! 1639 } else {
2101 !! 1640 $contents .= $1."\n";
2102 if (($declaration_purpose eq "") && $ !! 1641 }
2103 emit_warning("${file}:$.", "missi !! 1642 } else {
2104 } !! 1643 # i dont know - bad line? ignore.
2105 !! 1644 print STDERR "Warning(${file}:$.): bad line: $_";
2106 if ($identifier eq "" && $decl_type n !! 1645 ++$warnings;
2107 emit_warning("${file}:$.", "wrong !! 1646 }
2108 $state = STATE_NORMAL; !! 1647 } elsif ($state == 3) { # scanning for function { (end of prototype)
2109 } !! 1648 if ($decl_type eq 'function') {
2110 !! 1649 process_state3_function($_, $file);
2111 if ($verbose) { !! 1650 } else {
2112 print STDERR "${file}:$.: info: S !! 1651 process_state3_type($_, $file);
2113 } !! 1652 }
2114 } else { !! 1653 } elsif ($state == 4) {
2115 emit_warning("${file}:$.", "Cannot un !! 1654 # Documentation block
2116 $state = STATE_NORMAL; !! 1655 if (/$doc_block/) {
2117 } !! 1656 dump_section($section, $contents);
2118 } !! 1657 output_intro({'sectionlist' => \@sectionlist,
2119 !! 1658 'sections' => \%sections });
2120 !! 1659 $contents = "";
2121 # !! 1660 $function = "";
2122 # STATE_BODY and STATE_BODY_MAYBE: the bulk o !! 1661 %constants = ();
2123 # !! 1662 %parameterdescs = ();
2124 sub process_body($$) { !! 1663 %parametertypes = ();
2125 my $file = shift; !! 1664 @parameterlist = ();
2126 !! 1665 %sections = ();
2127 if ($state == STATE_BODY_WITH_BLANK_LINE !! 1666 @sectionlist = ();
2128 dump_section($file, $section, $conten !! 1667 $prototype = "";
2129 $section = $section_default; !! 1668 if ( $1 eq "" ) {
2130 $new_start_line = $.; !! 1669 $section = $section_intro;
2131 $contents = ""; !! 1670 } else {
2132 } !! 1671 $section = $1;
2133 !! 1672 }
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 } 1673 }
2217 $cont =~ s/^$leading_space//; !! 1674 elsif (/$doc_end/)
2218 } !! 1675 {
2219 $contents .= $cont . "\n"; !! 1676 dump_section($section, $contents);
2220 } !! 1677 output_intro({'sectionlist' => \@sectionlist,
2221 } else { !! 1678 'sections' => \%sections });
2222 # i dont know - bad line? ignore. !! 1679 $contents = "";
2223 emit_warning("${file}:$.", "bad line: !! 1680 $function = "";
2224 } !! 1681 %constants = ();
2225 } !! 1682 %parameterdescs = ();
2226 !! 1683 %parametertypes = ();
2227 !! 1684 @parameterlist = ();
2228 # !! 1685 %sections = ();
2229 # STATE_PROTO: reading a function/whatever pr !! 1686 @sectionlist = ();
2230 # !! 1687 $prototype = "";
2231 sub process_proto($$) { !! 1688 $state = 0;
2232 my $file = shift; !! 1689 }
2233 !! 1690 elsif (/$doc_content/)
2234 if (/$doc_inline_oneline/) { !! 1691 {
2235 $section = $1; !! 1692 if ( $1 eq "" )
2236 $contents = $2; !! 1693 {
2237 if ($contents ne "") { !! 1694 $contents .= $blankline;
2238 $contents .= "\n"; !! 1695 }
2239 dump_section($file, $section, $co !! 1696 else
2240 $section = $section_default; !! 1697 {
2241 $contents = ""; !! 1698 $contents .= $1 . "\n";
2242 } !! 1699 }
2243 } elsif (/$doc_inline_start/) { !! 1700 }
2244 $state = STATE_INLINE; !! 1701 }
2245 $inline_doc_state = STATE_INLINE_NAME !! 1702 }
2246 } elsif ($decl_type eq 'function') { !! 1703 if ($initial_section_counter == $section_counter) {
2247 process_proto_function($_, $file); !! 1704 print STDERR "Warning(${file}): no structured comments found\n";
2248 } else { !! 1705 if ($output_mode eq "sgml") {
2249 process_proto_type($_, $file); !! 1706 # The template wants at least one RefEntry here; make one.
2250 } !! 1707 print "<refentry>\n";
2251 } !! 1708 print " <refnamediv>\n";
2252 !! 1709 print " <refname>\n";
2253 # !! 1710 print " ${file}\n";
2254 # STATE_DOCBLOCK: within a DOC: block. !! 1711 print " </refname>\n";
2255 # !! 1712 print " <refpurpose>\n";
2256 sub process_docblock($$) { !! 1713 print " Document generation inconsistency\n";
2257 my $file = shift; !! 1714 print " </refpurpose>\n";
2258 !! 1715 print " </refnamediv>\n";
2259 if (/$doc_end/) { !! 1716 print " <refsect1>\n";
2260 dump_doc_section($file, $section, $co !! 1717 print " <title>\n";
2261 $section = $section_default; !! 1718 print " Oops\n";
2262 $contents = ""; !! 1719 print " </title>\n";
2263 $function = ""; !! 1720 print " <warning>\n";
2264 %parameterdescs = (); !! 1721 print " <para>\n";
2265 %parametertypes = (); !! 1722 print " The template for this document tried to insert\n";
2266 @parameterlist = (); !! 1723 print " the structured comment from the file\n";
2267 %sections = (); !! 1724 print " <filename>${file}</filename> at this point,\n";
2268 @sectionlist = (); !! 1725 print " but none was found.\n";
2269 $prototype = ""; !! 1726 print " This dummy section is inserted to allow\n";
2270 $state = STATE_NORMAL; !! 1727 print " generation to continue.\n";
2271 } elsif (/$doc_content/) { !! 1728 print " </para>\n";
2272 if ( $1 eq "" ) { !! 1729 print " </warning>\n";
2273 $contents .= $blankline; !! 1730 print " </refsect1>\n";
2274 } else { !! 1731 print "</refentry>\n";
2275 $contents .= $1 . "\n"; !! 1732 }
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 } 1733 }
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 } 1734 }
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.