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

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

194#
195#
196# All descriptive text is further processed, scanning for the following special
197# patterns, which are highlighted appropriately.
198#
199# 'funcname()' - function
200# '$ENVVAR' - environmental variable
201# '&struct_name' - name of a structure (up to two words including 'struct')
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

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

194#
195#
196# All descriptive text is further processed, scanning for the following special
197# patterns, which are highlighted appropriately.
198#
199# 'funcname()' - function
200# '$ENVVAR' - environmental variable
201# '&struct_name' - name of a structure (up to two words including 'struct')
202# '&struct_name.member' - name of a structure member
202# '@parameter' - name of a parameter
203# '%CONST' - name of a constant.
204
205## init lots of data
206
203# '@parameter' - name of a parameter
204# '%CONST' - name of a constant.
205
206## init lots of data
207
207
208my $errors = 0;
209my $warnings = 0;
210my $anon_struct_union = 0;
211
212# match expressions used to find embedded type information
213my $type_constant = '\%([-_\w]+)';
214my $type_func = '(\w+)\(\)';
215my $type_param = '\@(\w+(\.\.\.)?)';
216my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
208my $errors = 0;
209my $warnings = 0;
210my $anon_struct_union = 0;
211
212# match expressions used to find embedded type information
213my $type_constant = '\%([-_\w]+)';
214my $type_func = '(\w+)\(\)';
215my $type_param = '\@(\w+(\.\.\.)?)';
216my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
217my $type_struct = '\&((struct\s*)*[_\w]+)';
218my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
219my $type_env = '(\$\w+)';
217my $type_env = '(\$\w+)';
220my $type_enum_full = '\&(enum)\s*([_\w]+)';
221my $type_struct_full = '\&(struct)\s*([_\w]+)';
222my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
223my $type_union_full = '\&(union)\s*([_\w]+)';
224my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
218my $type_enum = '\&(enum\s*([_\w]+))';
219my $type_struct = '\&(struct\s*([_\w]+))';
220my $type_typedef = '\&(typedef\s*([_\w]+))';
221my $type_union = '\&(union\s*([_\w]+))';
222my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
223my $type_fallback = '\&([_\w]+)';
224my $type_enum_xml = '\&amp;(enum\s*([_\w]+))';
225my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
226my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
227my $type_union_xml = '\&amp;(union\s*([_\w]+))';
228my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
229my $type_fallback_xml = '\&amp([_\w]+)';
225my $type_member_func = $type_member . '\(\)';
226
227# Output conversion substitutions.
228# One for each output format
229
230# these work fairly well
231my @highlights_html = (
232 [$type_constant, "<i>\$1</i>"],
233 [$type_func, "<b>\$1</b>"],
230my $type_member_func = $type_member . '\(\)';
231
232# Output conversion substitutions.
233# One for each output format
234
235# these work fairly well
236my @highlights_html = (
237 [$type_constant, "<i>\$1</i>"],
238 [$type_func, "<b>\$1</b>"],
239 [$type_enum_xml, "<i>\$1</i>"],
234 [$type_struct_xml, "<i>\$1</i>"],
240 [$type_struct_xml, "<i>\$1</i>"],
241 [$type_typedef_xml, "<i>\$1</i>"],
242 [$type_union_xml, "<i>\$1</i>"],
235 [$type_env, "<b><i>\$1</i></b>"],
243 [$type_env, "<b><i>\$1</i></b>"],
236 [$type_param, "<tt><b>\$1</b></tt>"]
244 [$type_param, "<tt><b>\$1</b></tt>"],
245 [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"],
246 [$type_fallback_xml, "<i>\$1</i>"]
237 );
238my $local_lt = "\\\\\\\\lt:";
239my $local_gt = "\\\\\\\\gt:";
240my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
241
242# html version 5
243my @highlights_html5 = (
244 [$type_constant, "<span class=\"const\">\$1</span>"],
245 [$type_func, "<span class=\"func\">\$1</span>"],
247 );
248my $local_lt = "\\\\\\\\lt:";
249my $local_gt = "\\\\\\\\gt:";
250my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
251
252# html version 5
253my @highlights_html5 = (
254 [$type_constant, "<span class=\"const\">\$1</span>"],
255 [$type_func, "<span class=\"func\">\$1</span>"],
256 [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
246 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
257 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
258 [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"],
259 [$type_union_xml, "<span class=\"union\">\$1</span>"],
247 [$type_env, "<span class=\"env\">\$1</span>"],
260 [$type_env, "<span class=\"env\">\$1</span>"],
248 [$type_param, "<span class=\"param\">\$1</span>]"]
261 [$type_param, "<span class=\"param\">\$1</span>]"],
262 [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"],
263 [$type_fallback_xml, "<span class=\"struct\">\$1</span>"]
249 );
250my $blankline_html5 = $local_lt . "br /" . $local_gt;
251
252# XML, docbook format
253my @highlights_xml = (
254 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
255 [$type_constant, "<constant>\$1</constant>"],
264 );
265my $blankline_html5 = $local_lt . "br /" . $local_gt;
266
267# XML, docbook format
268my @highlights_xml = (
269 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
270 [$type_constant, "<constant>\$1</constant>"],
271 [$type_enum_xml, "<type>\$1</type>"],
256 [$type_struct_xml, "<structname>\$1</structname>"],
272 [$type_struct_xml, "<structname>\$1</structname>"],
273 [$type_typedef_xml, "<type>\$1</type>"],
274 [$type_union_xml, "<structname>\$1</structname>"],
257 [$type_param, "<parameter>\$1</parameter>"],
258 [$type_func, "<function>\$1</function>"],
275 [$type_param, "<parameter>\$1</parameter>"],
276 [$type_func, "<function>\$1</function>"],
259 [$type_env, "<envar>\$1</envar>"]
277 [$type_env, "<envar>\$1</envar>"],
278 [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
279 [$type_fallback_xml, "<structname>\$1</structname>"]
260 );
261my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
262
263# gnome, docbook format
264my @highlights_gnome = (
265 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
266 [$type_func, "<function>\$1</function>"],
280 );
281my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
282
283# gnome, docbook format
284my @highlights_gnome = (
285 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
286 [$type_func, "<function>\$1</function>"],
287 [$type_enum, "<type>\$1</type>"],
267 [$type_struct, "<structname>\$1</structname>"],
288 [$type_struct, "<structname>\$1</structname>"],
289 [$type_typedef, "<type>\$1</type>"],
290 [$type_union, "<structname>\$1</structname>"],
268 [$type_env, "<envar>\$1</envar>"],
291 [$type_env, "<envar>\$1</envar>"],
269 [$type_param, "<parameter>\$1</parameter>" ]
292 [$type_param, "<parameter>\$1</parameter>" ],
293 [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
294 [$type_fallback, "<structname>\$1</structname>"]
270 );
271my $blankline_gnome = "</para><para>\n";
272
273# these are pretty rough
274my @highlights_man = (
275 [$type_constant, "\$1"],
276 [$type_func, "\\\\fB\$1\\\\fP"],
295 );
296my $blankline_gnome = "</para><para>\n";
297
298# these are pretty rough
299my @highlights_man = (
300 [$type_constant, "\$1"],
301 [$type_func, "\\\\fB\$1\\\\fP"],
302 [$type_enum, "\\\\fI\$1\\\\fP"],
277 [$type_struct, "\\\\fI\$1\\\\fP"],
303 [$type_struct, "\\\\fI\$1\\\\fP"],
278 [$type_param, "\\\\fI\$1\\\\fP"]
304 [$type_typedef, "\\\\fI\$1\\\\fP"],
305 [$type_union, "\\\\fI\$1\\\\fP"],
306 [$type_param, "\\\\fI\$1\\\\fP"],
307 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
308 [$type_fallback, "\\\\fI\$1\\\\fP"]
279 );
280my $blankline_man = "";
281
282# text-mode
283my @highlights_text = (
284 [$type_constant, "\$1"],
285 [$type_func, "\$1"],
309 );
310my $blankline_man = "";
311
312# text-mode
313my @highlights_text = (
314 [$type_constant, "\$1"],
315 [$type_func, "\$1"],
316 [$type_enum, "\$1"],
286 [$type_struct, "\$1"],
317 [$type_struct, "\$1"],
287 [$type_param, "\$1"]
318 [$type_typedef, "\$1"],
319 [$type_union, "\$1"],
320 [$type_param, "\$1"],
321 [$type_member, "\$1\$2\$3"],
322 [$type_fallback, "\$1"]
288 );
289my $blankline_text = "";
290
291# rst-mode
292my @highlights_rst = (
293 [$type_constant, "``\$1``"],
294 # Note: need to escape () to avoid func matching later
323 );
324my $blankline_text = "";
325
326# rst-mode
327my @highlights_rst = (
328 [$type_constant, "``\$1``"],
329 # Note: need to escape () to avoid func matching later
295 [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
296 [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
330 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
331 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
297 [$type_fp_param, "**\$1\\\\(\\\\)**"],
298 [$type_func, "\\:c\\:func\\:`\$1()`"],
332 [$type_fp_param, "**\$1\\\\(\\\\)**"],
333 [$type_func, "\\:c\\:func\\:`\$1()`"],
299 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
300 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
301 [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
302 [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
334 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
335 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
336 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
337 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
303 # in rst this can refer to any type
338 # in rst this can refer to any type
304 [$type_struct, "\\:c\\:type\\:`\$1`"],
339 [$type_fallback, "\\:c\\:type\\:`\$1`"],
305 [$type_param, "**\$1**"]
306 );
307my $blankline_rst = "\n";
308
309# list mode
310my @highlights_list = (
311 [$type_constant, "\$1"],
312 [$type_func, "\$1"],
340 [$type_param, "**\$1**"]
341 );
342my $blankline_rst = "\n";
343
344# list mode
345my @highlights_list = (
346 [$type_constant, "\$1"],
347 [$type_func, "\$1"],
348 [$type_enum, "\$1"],
313 [$type_struct, "\$1"],
349 [$type_struct, "\$1"],
314 [$type_param, "\$1"]
350 [$type_typedef, "\$1"],
351 [$type_union, "\$1"],
352 [$type_param, "\$1"],
353 [$type_member, "\$1"],
354 [$type_fallback, "\$1"]
315 );
316my $blankline_list = "";
317
318# read arguments
319if ($#ARGV == -1) {
320 usage();
321}
322

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

1126
1127 # print parameters
1128 print "<refsect1>\n <title>Arguments</title>\n";
1129 if ($#{$args{'parameterlist'}} >= 0) {
1130 print " <variablelist>\n";
1131 foreach $parameter (@{$args{'parameterlist'}}) {
1132 my $parameter_name = $parameter;
1133 $parameter_name =~ s/\[.*//;
355 );
356my $blankline_list = "";
357
358# read arguments
359if ($#ARGV == -1) {
360 usage();
361}
362

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

1166
1167 # print parameters
1168 print "<refsect1>\n <title>Arguments</title>\n";
1169 if ($#{$args{'parameterlist'}} >= 0) {
1170 print " <variablelist>\n";
1171 foreach $parameter (@{$args{'parameterlist'}}) {
1172 my $parameter_name = $parameter;
1173 $parameter_name =~ s/\[.*//;
1174 $type = $args{'parametertypes'}{$parameter};
1134
1175
1135 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1176 print " <varlistentry>\n <term><parameter>$type $parameter</parameter></term>\n";
1136 print " <listitem>\n <para>\n";
1137 $lineprefix=" ";
1138 output_highlight($args{'parameterdescs'}{$parameter_name});
1139 print " </para>\n </listitem>\n </varlistentry>\n";
1140 }
1141 print " </variablelist>\n";
1142 } else {
1143 print " <para>\n None\n </para>\n";

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

1218 foreach $parameter (@{$args{'parameterlist'}}) {
1219 ($parameter =~ /^#/) && next;
1220
1221 my $parameter_name = $parameter;
1222 $parameter_name =~ s/\[.*//;
1223
1224 defined($args{'parameterdescs'}{$parameter_name}) || next;
1225 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1177 print " <listitem>\n <para>\n";
1178 $lineprefix=" ";
1179 output_highlight($args{'parameterdescs'}{$parameter_name});
1180 print " </para>\n </listitem>\n </varlistentry>\n";
1181 }
1182 print " </variablelist>\n";
1183 } else {
1184 print " <para>\n None\n </para>\n";

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

1259 foreach $parameter (@{$args{'parameterlist'}}) {
1260 ($parameter =~ /^#/) && next;
1261
1262 my $parameter_name = $parameter;
1263 $parameter_name =~ s/\[.*//;
1264
1265 defined($args{'parameterdescs'}{$parameter_name}) || next;
1266 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1267 $type = $args{'parametertypes'}{$parameter};
1226 print " <varlistentry>";
1268 print " <varlistentry>";
1227 print " <term>$parameter</term>\n";
1269 print " <term><literal>$type $parameter</literal></term>\n";
1228 print " <listitem><para>\n";
1229 output_highlight($args{'parameterdescs'}{$parameter_name});
1230 print " </para></listitem>\n";
1231 print " </varlistentry>\n";
1232 }
1233 print " </variablelist>\n";
1234 } else {
1235 print " <para>\n None\n </para>\n";

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

1878 output_highlight_rst($args{'purpose'});
1879 print "\n";
1880 }
1881
1882 print "**Parameters**\n\n";
1883 $lineprefix = " ";
1884 foreach $parameter (@{$args{'parameterlist'}}) {
1885 my $parameter_name = $parameter;
1270 print " <listitem><para>\n";
1271 output_highlight($args{'parameterdescs'}{$parameter_name});
1272 print " </para></listitem>\n";
1273 print " </varlistentry>\n";
1274 }
1275 print " </variablelist>\n";
1276 } else {
1277 print " <para>\n None\n </para>\n";

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

1920 output_highlight_rst($args{'purpose'});
1921 print "\n";
1922 }
1923
1924 print "**Parameters**\n\n";
1925 $lineprefix = " ";
1926 foreach $parameter (@{$args{'parameterlist'}}) {
1927 my $parameter_name = $parameter;
1886 #$parameter_name =~ s/\[.*//;
1928 $parameter_name =~ s/\[.*//;
1887 $type = $args{'parametertypes'}{$parameter};
1888
1889 if ($type ne "") {
1890 print "``$type $parameter``\n";
1891 } else {
1892 print "``$parameter``\n";
1893 }
1894

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

2404 # this fixes a problem where check_sections() cannot find
2405 # a parameter like "addr[6 + 2]" because it actually appears
2406 # as "addr[6", "+", "2]" on the parameter list;
2407 # but it's better to maintain the param string unchanged for output,
2408 # so just weaken the string compare in check_sections() to ignore
2409 # "[blah" in a parameter string;
2410 ###$param =~ s/\s*//g;
2411 push @parameterlist, $param;
1929 $type = $args{'parametertypes'}{$parameter};
1930
1931 if ($type ne "") {
1932 print "``$type $parameter``\n";
1933 } else {
1934 print "``$parameter``\n";
1935 }
1936

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

2446 # this fixes a problem where check_sections() cannot find
2447 # a parameter like "addr[6 + 2]" because it actually appears
2448 # as "addr[6", "+", "2]" on the parameter list;
2449 # but it's better to maintain the param string unchanged for output,
2450 # so just weaken the string compare in check_sections() to ignore
2451 # "[blah" in a parameter string;
2452 ###$param =~ s/\s*//g;
2453 push @parameterlist, $param;
2454 $type =~ s/\s\s+/ /g;
2412 $parametertypes{$param} = $type;
2413}
2414
2415sub check_sections($$$$$$) {
2416 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2417 my @sects = split ' ', $sectcheck;
2418 my @prms = split ' ', $prmscheck;
2419 my $err;

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

2500 $prototype =~ s/^__always_inline +//;
2501 $prototype =~ s/^noinline +//;
2502 $prototype =~ s/__init +//;
2503 $prototype =~ s/__init_or_module +//;
2504 $prototype =~ s/__meminit +//;
2505 $prototype =~ s/__must_check +//;
2506 $prototype =~ s/__weak +//;
2507 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2455 $parametertypes{$param} = $type;
2456}
2457
2458sub check_sections($$$$$$) {
2459 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2460 my @sects = split ' ', $sectcheck;
2461 my @prms = split ' ', $prmscheck;
2462 my $err;

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

2543 $prototype =~ s/^__always_inline +//;
2544 $prototype =~ s/^noinline +//;
2545 $prototype =~ s/__init +//;
2546 $prototype =~ s/__init_or_module +//;
2547 $prototype =~ s/__meminit +//;
2548 $prototype =~ s/__must_check +//;
2549 $prototype =~ s/__weak +//;
2550 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2508 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2551 $prototype =~ s/__attribute__\s*\(\(
2552 (?:
2553 [\w\s]++ # attribute name
2554 (?:\([^)]*+\))? # attribute arguments
2555 \s*+,? # optional comma at the end
2556 )+
2557 \)\)\s+//x;
2509
2510 # Yes, this truly is vile. We are looking for:
2511 # 1. Return type (may be nothing if we're looking at a macro)
2512 # 2. Function name
2513 # 3. Function parameters.
2514 #
2515 # All the while we have to watch out for function pointer parameters
2516 # (which IIRC is what the two sections are for), C types (these

--- 640 unchanged lines hidden --- 		2558
2559 # Yes, this truly is vile. We are looking for:
2560 # 1. Return type (may be nothing if we're looking at a macro)
2561 # 2. Function name
2562 # 3. Function parameters.
2563 #
2564 # All the while we have to watch out for function pointer parameters
2565 # (which IIRC is what the two sections are for), C types (these

--- 640 unchanged lines hidden ---