kernel-doc (60c07f80b04698f6c054b675cb67ec5e7ee8db27) kernel-doc (0b0f5f29b282b18d26ce698e1aab0267234f77bf)
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 ##

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

54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
58 -rst Output reStructuredText format.
59 -text Output plain text format.
60
61Output selection (mutually exclusive):
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 ##

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

54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
58 -rst Output reStructuredText format.
59 -text Output plain text format.
60
61Output selection (mutually exclusive):
62 -export Only output documentation for symbols that have been
63 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
64 in the same FILE.
65 -internal Only output documentation for symbols that have NOT been
66 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
67 in the same FILE.
62 -function NAME Only output documentation for the given function(s)
63 or DOC: section title(s). All other functions and DOC:
64 sections are ignored. May be specified multiple times.
65 -nofunction NAME Do NOT output documentation for the given function(s);
66 only output documentation for the other functions and
67 DOC: sections. May be specified multiple times.
68
69Output selection modifiers:
70 -no-doc-sections Do not output DOC: sections.
68 -function NAME Only output documentation for the given function(s)
69 or DOC: section title(s). All other functions and DOC:
70 sections are ignored. May be specified multiple times.
71 -nofunction NAME Do NOT output documentation for the given function(s);
72 only output documentation for the other functions and
73 DOC: sections. May be specified multiple times.
74
75Output selection modifiers:
76 -no-doc-sections Do not output DOC: sections.
77 -enable-lineno Enable output of #define LINENO lines. Only works with
78 reStructuredText format.
71
72Other parameters:
73 -v Verbose output, more warnings and other information.
74 -h Print this help.
75
76EOF
77 print $message;
78 exit 1;

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

201my $type_constant = '\%([-_\w]+)';
202my $type_func = '(\w+)\(\)';
203my $type_param = '\@(\w+)';
204my $type_struct = '\&((struct\s*)*[_\w]+)';
205my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
206my $type_env = '(\$\w+)';
207my $type_enum_full = '\&(enum)\s*([_\w]+)';
208my $type_struct_full = '\&(struct)\s*([_\w]+)';
79
80Other parameters:
81 -v Verbose output, more warnings and other information.
82 -h Print this help.
83
84EOF
85 print $message;
86 exit 1;

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

209my $type_constant = '\%([-_\w]+)';
210my $type_func = '(\w+)\(\)';
211my $type_param = '\@(\w+)';
212my $type_struct = '\&((struct\s*)*[_\w]+)';
213my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
214my $type_env = '(\$\w+)';
215my $type_enum_full = '\&(enum)\s*([_\w]+)';
216my $type_struct_full = '\&(struct)\s*([_\w]+)';
217my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
218my $type_union_full = '\&(union)\s*([_\w]+)';
219my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
220my $type_member_func = $type_member . '\(\)';
209
210# Output conversion substitutions.
211# One for each output format
212
213# these work fairly well
214my @highlights_html = (
215 [$type_constant, "<i>\$1</i>"],
216 [$type_func, "<b>\$1</b>"],

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

269 [$type_struct, "\$1"],
270 [$type_param, "\$1"]
271 );
272my $blankline_text = "";
273
274# rst-mode
275my @highlights_rst = (
276 [$type_constant, "``\$1``"],
221
222# Output conversion substitutions.
223# One for each output format
224
225# these work fairly well
226my @highlights_html = (
227 [$type_constant, "<i>\$1</i>"],
228 [$type_func, "<b>\$1</b>"],

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

281 [$type_struct, "\$1"],
282 [$type_param, "\$1"]
283 );
284my $blankline_text = "";
285
286# rst-mode
287my @highlights_rst = (
288 [$type_constant, "``\$1``"],
277 [$type_func, "\\:c\\:func\\:`\$1`"],
289 # Note: need to escape () to avoid func matching later
290 [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
291 [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
292 [$type_func, "\\:c\\:func\\:`\$1()`"],
278 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
279 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
293 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
294 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
280 [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
295 [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
296 [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
297 # in rst this can refer to any type
298 [$type_struct, "\\:c\\:type\\:`\$1`"],
281 [$type_param, "**\$1**"]
282 );
283my $blankline_rst = "\n";
284
285# list mode
286my @highlights_list = (
287 [$type_constant, "\$1"],
288 [$type_func, "\$1"],

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

298
299my $kernelversion;
300my $dohighlight = "";
301
302my $verbose = 0;
303my $output_mode = "man";
304my $output_preformatted = 0;
305my $no_doc_sections = 0;
299 [$type_param, "**\$1**"]
300 );
301my $blankline_rst = "\n";
302
303# list mode
304my @highlights_list = (
305 [$type_constant, "\$1"],
306 [$type_func, "\$1"],

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

316
317my $kernelversion;
318my $dohighlight = "";
319
320my $verbose = 0;
321my $output_mode = "man";
322my $output_preformatted = 0;
323my $no_doc_sections = 0;
324my $enable_lineno = 0;
306my @highlights = @highlights_man;
307my $blankline = $blankline_man;
308my $modulename = "Kernel API";
325my @highlights = @highlights_man;
326my $blankline = $blankline_man;
327my $modulename = "Kernel API";
309my $function_only = 0;
328
329use constant {
330 OUTPUT_ALL => 0, # output all symbols and doc sections
331 OUTPUT_INCLUDE => 1, # output only specified symbols
332 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
333 OUTPUT_EXPORTED => 3, # output exported symbols
334 OUTPUT_INTERNAL => 4, # output non-exported symbols
335};
336my $output_selection = OUTPUT_ALL;
310my $show_not_found = 0;
311
312my @build_time;
313if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
314 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
315 @build_time = gmtime($seconds);
316} else {
317 @build_time = localtime;

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

322 'November', 'December')[$build_time[4]] .
323 " " . ($build_time[5]+1900);
324
325# Essentially these are globals.
326# They probably want to be tidied up, made more localised or something.
327# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
328# could cause "use of undefined value" or other bugs.
329my ($function, %function_table, %parametertypes, $declaration_purpose);
337my $show_not_found = 0;
338
339my @build_time;
340if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
341 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
342 @build_time = gmtime($seconds);
343} else {
344 @build_time = localtime;

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

349 'November', 'December')[$build_time[4]] .
350 " " . ($build_time[5]+1900);
351
352# Essentially these are globals.
353# They probably want to be tidied up, made more localised or something.
354# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
355# could cause "use of undefined value" or other bugs.
356my ($function, %function_table, %parametertypes, $declaration_purpose);
357my $declaration_start_line;
330my ($type, $declaration_name, $return_type);
331my ($newsection, $newcontents, $prototype, $brcount, %source_map);
332
333if (defined($ENV{'KBUILD_VERBOSE'})) {
334 $verbose = "$ENV{'KBUILD_VERBOSE'}";
335}
336
337# Generated docbook code is inserted in a template at a point where
338# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
339# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
340# We keep track of number of generated entries and generate a dummy
341# if needs be to ensure the expanded template can be postprocessed
342# into html.
343my $section_counter = 0;
344
345my $lineprefix="";
346
358my ($type, $declaration_name, $return_type);
359my ($newsection, $newcontents, $prototype, $brcount, %source_map);
360
361if (defined($ENV{'KBUILD_VERBOSE'})) {
362 $verbose = "$ENV{'KBUILD_VERBOSE'}";
363}
364
365# Generated docbook code is inserted in a template at a point where
366# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
367# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
368# We keep track of number of generated entries and generate a dummy
369# if needs be to ensure the expanded template can be postprocessed
370# into html.
371my $section_counter = 0;
372
373my $lineprefix="";
374
347# states
348# 0 - normal code
349# 1 - looking for function name
350# 2 - scanning field start.
351# 3 - scanning prototype.
352# 4 - documentation block
353# 5 - gathering documentation outside main block
375# Parser states
376use constant {
377 STATE_NORMAL => 0, # normal code
378 STATE_NAME => 1, # looking for function name
379 STATE_FIELD => 2, # scanning field start
380 STATE_PROTO => 3, # scanning prototype
381 STATE_DOCBLOCK => 4, # documentation block
382 STATE_INLINE => 5, # gathering documentation outside main block
383};
354my $state;
355my $in_doc_sect;
356
384my $state;
385my $in_doc_sect;
386
357# Split Doc State
358# 0 - Invalid (Before start or after finish)
359# 1 - Is started (the /** was found inside a struct)
360# 2 - The @parameter header was found, start accepting multi paragraph text.
361# 3 - Finished (the */ was found)
362# 4 - Error - Comment without header was found. Spit a warning as it's not
363# proper kernel-doc and ignore the rest.
364my $split_doc_state;
387# Inline documentation state
388use constant {
389 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
390 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
391 STATE_INLINE_TEXT => 2, # looking for member documentation
392 STATE_INLINE_END => 3, # done
393 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
394 # Spit a warning as it's not
395 # proper kernel-doc and ignore the rest.
396};
397my $inline_doc_state;
365
366#declaration types: can be
367# 'function', 'struct', 'union', 'enum', 'typedef'
368my $decl_type;
369
398
399#declaration types: can be
400# 'function', 'struct', 'union', 'enum', 'typedef'
401my $decl_type;
402
370my $doc_special = "\@\%\$\&";
371
372my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
373my $doc_end = '\*/';
374my $doc_com = '\s*\*\s*';
375my $doc_com_body = '\s*\* ?';
376my $doc_decl = $doc_com . '(\w+)';
403my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
404my $doc_end = '\*/';
405my $doc_com = '\s*\*\s*';
406my $doc_com_body = '\s*\* ?';
407my $doc_decl = $doc_com . '(\w+)';
377my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
408# @params and a strictly limited set of supported section names
409my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)';
378my $doc_content = $doc_com_body . '(.*)';
379my $doc_block = $doc_com . 'DOC:\s*(.*)?';
410my $doc_content = $doc_com_body . '(.*)';
411my $doc_block = $doc_com . 'DOC:\s*(.*)?';
380my $doc_split_start = '^\s*/\*\*\s*$';
381my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
382my $doc_split_end = '^\s*\*/\s*$';
412my $doc_inline_start = '^\s*/\*\*\s*$';
413my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
414my $doc_inline_end = '^\s*\*/\s*$';
415my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
383
416
384my %constants;
385my %parameterdescs;
417my %parameterdescs;
418my %parameterdesc_start_lines;
386my @parameterlist;
387my %sections;
388my @sectionlist;
419my @parameterlist;
420my %sections;
421my @sectionlist;
422my %section_start_lines;
389my $sectcheck;
390my $struct_actual;
391
392my $contents = "";
423my $sectcheck;
424my $struct_actual;
425
426my $contents = "";
427my $new_start_line = 0;
428
429# the canonical section names. see also $doc_sect above.
393my $section_default = "Description"; # default section
394my $section_intro = "Introduction";
395my $section = $section_default;
396my $section_context = "Context";
397my $section_return = "Return";
398
399my $undescribed = "-- undescribed --";
400

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

432 $blankline = $blankline_list;
433 } elsif ($cmd eq "-gnome") {
434 $output_mode = "gnome";
435 @highlights = @highlights_gnome;
436 $blankline = $blankline_gnome;
437 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
438 $modulename = shift @ARGV;
439 } elsif ($cmd eq "-function") { # to only output specific functions
430my $section_default = "Description"; # default section
431my $section_intro = "Introduction";
432my $section = $section_default;
433my $section_context = "Context";
434my $section_return = "Return";
435
436my $undescribed = "-- undescribed --";
437

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

469 $blankline = $blankline_list;
470 } elsif ($cmd eq "-gnome") {
471 $output_mode = "gnome";
472 @highlights = @highlights_gnome;
473 $blankline = $blankline_gnome;
474 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
475 $modulename = shift @ARGV;
476 } elsif ($cmd eq "-function") { # to only output specific functions
440 $function_only = 1;
477 $output_selection = OUTPUT_INCLUDE;
441 $function = shift @ARGV;
442 $function_table{$function} = 1;
478 $function = shift @ARGV;
479 $function_table{$function} = 1;
443 } elsif ($cmd eq "-nofunction") { # to only output specific functions
444 $function_only = 2;
480 } elsif ($cmd eq "-nofunction") { # output all except specific functions
481 $output_selection = OUTPUT_EXCLUDE;
445 $function = shift @ARGV;
446 $function_table{$function} = 1;
482 $function = shift @ARGV;
483 $function_table{$function} = 1;
484 } elsif ($cmd eq "-export") { # only exported symbols
485 $output_selection = OUTPUT_EXPORTED;
486 %function_table = ()
487 } elsif ($cmd eq "-internal") { # only non-exported symbols
488 $output_selection = OUTPUT_INTERNAL;
489 %function_table = ()
447 } elsif ($cmd eq "-v") {
448 $verbose = 1;
449 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
450 usage();
451 } elsif ($cmd eq '-no-doc-sections') {
452 $no_doc_sections = 1;
490 } elsif ($cmd eq "-v") {
491 $verbose = 1;
492 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
493 usage();
494 } elsif ($cmd eq '-no-doc-sections') {
495 $no_doc_sections = 1;
496 } elsif ($cmd eq '-enable-lineno') {
497 $enable_lineno = 1;
453 } elsif ($cmd eq '-show-not-found') {
454 $show_not_found = 1;
455 }
456}
457
458# continue execution near EOF;
459
460# get kernel version from env
461sub get_kernel_version() {
462 my $version = 'unknown kernel version';
463
464 if (defined($ENV{'KERNELVERSION'})) {
465 $version = $ENV{'KERNELVERSION'};
466 }
467 return $version;
468}
469
498 } elsif ($cmd eq '-show-not-found') {
499 $show_not_found = 1;
500 }
501}
502
503# continue execution near EOF;
504
505# get kernel version from env
506sub get_kernel_version() {
507 my $version = 'unknown kernel version';
508
509 if (defined($ENV{'KERNELVERSION'})) {
510 $version = $ENV{'KERNELVERSION'};
511 }
512 return $version;
513}
514
515#
516sub print_lineno {
517 my $lineno = shift;
518 if ($enable_lineno && defined($lineno)) {
519 print "#define LINENO " . $lineno . "\n";
520 }
521}
470##
471# dumps section contents to arrays/hashes intended for that purpose.
472#
473sub dump_section {
474 my $file = shift;
475 my $name = shift;
476 my $contents = join "\n", @_;
477
522##
523# dumps section contents to arrays/hashes intended for that purpose.
524#
525sub dump_section {
526 my $file = shift;
527 my $name = shift;
528 my $contents = join "\n", @_;
529
478 if ($name =~ m/$type_constant/) {
479 $name = $1;
480# print STDERR "constant section '$1' = '$contents'\n";
481 $constants{$name} = $contents;
482 } elsif ($name =~ m/$type_param/) {
530 if ($name =~ m/$type_param/) {
483# print STDERR "parameter def '$1' = '$contents'\n";
484 $name = $1;
485 $parameterdescs{$name} = $contents;
486 $sectcheck = $sectcheck . $name . " ";
531# print STDERR "parameter def '$1' = '$contents'\n";
532 $name = $1;
533 $parameterdescs{$name} = $contents;
534 $sectcheck = $sectcheck . $name . " ";
535 $parameterdesc_start_lines{$name} = $new_start_line;
536 $new_start_line = 0;
487 } elsif ($name eq "@\.\.\.") {
488# print STDERR "parameter def '...' = '$contents'\n";
489 $name = "...";
490 $parameterdescs{$name} = $contents;
491 $sectcheck = $sectcheck . $name . " ";
537 } elsif ($name eq "@\.\.\.") {
538# print STDERR "parameter def '...' = '$contents'\n";
539 $name = "...";
540 $parameterdescs{$name} = $contents;
541 $sectcheck = $sectcheck . $name . " ";
542 $parameterdesc_start_lines{$name} = $new_start_line;
543 $new_start_line = 0;
492 } else {
493# print STDERR "other section '$name' = '$contents'\n";
494 if (defined($sections{$name}) && ($sections{$name} ne "")) {
544 } else {
545# print STDERR "other section '$name' = '$contents'\n";
546 if (defined($sections{$name}) && ($sections{$name} ne "")) {
495 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
496 ++$errors;
547 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
548 ++$warnings;
549 $sections{$name} .= $contents;
550 } else {
551 $sections{$name} = $contents;
552 push @sectionlist, $name;
553 $section_start_lines{$name} = $new_start_line;
554 $new_start_line = 0;
497 }
555 }
498 $sections{$name} = $contents;
499 push @sectionlist, $name;
500 }
501}
502
503##
504# dump DOC: section after checking that it should go out
505#
506sub dump_doc_section {
507 my $file = shift;
508 my $name = shift;
509 my $contents = join "\n", @_;
510
511 if ($no_doc_sections) {
512 return;
513 }
514
556 }
557}
558
559##
560# dump DOC: section after checking that it should go out
561#
562sub dump_doc_section {
563 my $file = shift;
564 my $name = shift;
565 my $contents = join "\n", @_;
566
567 if ($no_doc_sections) {
568 return;
569 }
570
515 if (($function_only == 0) ||
516 ( $function_only == 1 && defined($function_table{$name})) ||
517 ( $function_only == 2 && !defined($function_table{$name})))
571 if (($output_selection == OUTPUT_ALL) ||
572 ($output_selection == OUTPUT_INCLUDE &&
573 defined($function_table{$name})) ||
574 ($output_selection == OUTPUT_EXCLUDE &&
575 !defined($function_table{$name})))
518 {
519 dump_section($file, $name, $contents);
520 output_blockhead({'sectionlist' => \@sectionlist,
521 'sections' => \%sections,
522 'module' => $modulename,
576 {
577 dump_section($file, $name, $contents);
578 output_blockhead({'sectionlist' => \@sectionlist,
579 'sections' => \%sections,
580 'module' => $modulename,
523 'content-only' => ($function_only != 0), });
581 'content-only' => ($output_selection != OUTPUT_ALL), });
524 }
525}
526
527##
528# output function
529#
530# parameterdescs, a hash.
531# function => "function name"

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

1731# starts by putting out the name of the doc section itself, but that tends
1732# to duplicate a header already in the template file.
1733#
1734sub output_blockhead_rst(%) {
1735 my %args = %{$_[0]};
1736 my ($parameter, $section);
1737
1738 foreach $section (@{$args{'sectionlist'}}) {
582 }
583}
584
585##
586# output function
587#
588# parameterdescs, a hash.
589# function => "function name"

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

1789# starts by putting out the name of the doc section itself, but that tends
1790# to duplicate a header already in the template file.
1791#
1792sub output_blockhead_rst(%) {
1793 my %args = %{$_[0]};
1794 my ($parameter, $section);
1795
1796 foreach $section (@{$args{'sectionlist'}}) {
1739 print "**$section**\n\n";
1797 if ($output_selection != OUTPUT_INCLUDE) {
1798 print "**$section**\n\n";
1799 }
1800 print_lineno($section_start_lines{$section});
1740 output_highlight_rst($args{'sections'}{$section});
1741 print "\n";
1742 }
1743}
1744
1745sub output_highlight_rst {
1746 my $contents = join "\n",@_;
1747 my $line;
1748
1749 # undo the evil effects of xml_escape() earlier
1750 $contents = xml_unescape($contents);
1751
1752 eval $dohighlight;
1753 die $@ if $@;
1754
1755 foreach $line (split "\n", $contents) {
1801 output_highlight_rst($args{'sections'}{$section});
1802 print "\n";
1803 }
1804}
1805
1806sub output_highlight_rst {
1807 my $contents = join "\n",@_;
1808 my $line;
1809
1810 # undo the evil effects of xml_escape() earlier
1811 $contents = xml_unescape($contents);
1812
1813 eval $dohighlight;
1814 die $@ if $@;
1815
1816 foreach $line (split "\n", $contents) {
1756 if ($line eq "") {
1757 print $lineprefix, $blankline;
1758 } else {
1759 $line =~ s/\\\\\\/\&/g;
1760 print $lineprefix, $line;
1761 }
1762 print "\n";
1817 print $lineprefix . $line . "\n";
1763 }
1764}
1765
1766sub output_function_rst(%) {
1767 my %args = %{$_[0]};
1768 my ($parameter, $section);
1818 }
1819}
1820
1821sub output_function_rst(%) {
1822 my %args = %{$_[0]};
1823 my ($parameter, $section);
1824 my $oldprefix = $lineprefix;
1769 my $start;
1770
1771 print ".. c:function:: ";
1772 if ($args{'functiontype'} ne "") {
1773 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1774 } else {
1775 $start = $args{'function'} . " (";
1776 }

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

1785 $type = $args{'parametertypes'}{$parameter};
1786 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1787 # pointer-to-function
1788 print $1 . $parameter . ") (" . $2;
1789 } else {
1790 print $type . " " . $parameter;
1791 }
1792 }
1825 my $start;
1826
1827 print ".. c:function:: ";
1828 if ($args{'functiontype'} ne "") {
1829 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1830 } else {
1831 $start = $args{'function'} . " (";
1832 }

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

1841 $type = $args{'parametertypes'}{$parameter};
1842 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1843 # pointer-to-function
1844 print $1 . $parameter . ") (" . $2;
1845 } else {
1846 print $type . " " . $parameter;
1847 }
1848 }
1793 print ")\n\n " . $args{'purpose'} . "\n\n";
1849 print ")\n\n";
1850 print_lineno($declaration_start_line);
1851 $lineprefix = " ";
1852 output_highlight_rst($args{'purpose'});
1853 print "\n";
1794
1854
1795 print ":Parameters:\n\n";
1855 print "**Parameters**\n\n";
1856 $lineprefix = " ";
1796 foreach $parameter (@{$args{'parameterlist'}}) {
1797 my $parameter_name = $parameter;
1798 #$parameter_name =~ s/\[.*//;
1799 $type = $args{'parametertypes'}{$parameter};
1800
1801 if ($type ne "") {
1857 foreach $parameter (@{$args{'parameterlist'}}) {
1858 my $parameter_name = $parameter;
1859 #$parameter_name =~ s/\[.*//;
1860 $type = $args{'parametertypes'}{$parameter};
1861
1862 if ($type ne "") {
1802 print " ``$type $parameter``\n";
1863 print "``$type $parameter``\n";
1803 } else {
1864 } else {
1804 print " ``$parameter``\n";
1865 print "``$parameter``\n";
1805 }
1866 }
1806 if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807 my $oldprefix = $lineprefix;
1808 $lineprefix = " ";
1867
1868 print_lineno($parameterdesc_start_lines{$parameter_name});
1869
1870 if (defined($args{'parameterdescs'}{$parameter_name}) &&
1871 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1809 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1872 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810 $lineprefix = $oldprefix;
1811 } else {
1873 } else {
1812 print "\n _undescribed_\n";
1874 print " *undescribed*\n";
1813 }
1814 print "\n";
1815 }
1875 }
1876 print "\n";
1877 }
1878
1879 $lineprefix = $oldprefix;
1816 output_section_rst(@_);
1817}
1818
1819sub output_section_rst(%) {
1820 my %args = %{$_[0]};
1821 my $section;
1822 my $oldprefix = $lineprefix;
1880 output_section_rst(@_);
1881}
1882
1883sub output_section_rst(%) {
1884 my %args = %{$_[0]};
1885 my $section;
1886 my $oldprefix = $lineprefix;
1823 $lineprefix = " ";
1887 $lineprefix = "";
1824
1825 foreach $section (@{$args{'sectionlist'}}) {
1888
1889 foreach $section (@{$args{'sectionlist'}}) {
1826 print ":$section:\n\n";
1890 print "**$section**\n\n";
1891 print_lineno($section_start_lines{$section});
1827 output_highlight_rst($args{'sections'}{$section});
1828 print "\n";
1829 }
1830 print "\n";
1831 $lineprefix = $oldprefix;
1832}
1833
1834sub output_enum_rst(%) {
1835 my %args = %{$_[0]};
1836 my ($parameter);
1892 output_highlight_rst($args{'sections'}{$section});
1893 print "\n";
1894 }
1895 print "\n";
1896 $lineprefix = $oldprefix;
1897}
1898
1899sub output_enum_rst(%) {
1900 my %args = %{$_[0]};
1901 my ($parameter);
1902 my $oldprefix = $lineprefix;
1837 my $count;
1838 my $name = "enum " . $args{'enum'};
1839
1840 print "\n\n.. c:type:: " . $name . "\n\n";
1903 my $count;
1904 my $name = "enum " . $args{'enum'};
1905
1906 print "\n\n.. c:type:: " . $name . "\n\n";
1841 print " " . $args{'purpose'} . "\n\n";
1907 print_lineno($declaration_start_line);
1908 $lineprefix = " ";
1909 output_highlight_rst($args{'purpose'});
1910 print "\n";
1842
1911
1843 print "..\n\n:Constants:\n\n";
1844 my $oldprefix = $lineprefix;
1845 $lineprefix = " ";
1912 print "**Constants**\n\n";
1913 $lineprefix = " ";
1846 foreach $parameter (@{$args{'parameterlist'}}) {
1914 foreach $parameter (@{$args{'parameterlist'}}) {
1847 print " `$parameter`\n";
1915 print "``$parameter``\n";
1848 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1849 output_highlight_rst($args{'parameterdescs'}{$parameter});
1850 } else {
1916 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1917 output_highlight_rst($args{'parameterdescs'}{$parameter});
1918 } else {
1851 print " undescribed\n";
1919 print " *undescribed*\n";
1852 }
1853 print "\n";
1854 }
1920 }
1921 print "\n";
1922 }
1923
1855 $lineprefix = $oldprefix;
1856 output_section_rst(@_);
1857}
1858
1859sub output_typedef_rst(%) {
1860 my %args = %{$_[0]};
1861 my ($parameter);
1924 $lineprefix = $oldprefix;
1925 output_section_rst(@_);
1926}
1927
1928sub output_typedef_rst(%) {
1929 my %args = %{$_[0]};
1930 my ($parameter);
1862 my $count;
1931 my $oldprefix = $lineprefix;
1863 my $name = "typedef " . $args{'typedef'};
1864
1932 my $name = "typedef " . $args{'typedef'};
1933
1865 ### FIXME: should the name below contain "typedef" or not?
1866 print "\n\n.. c:type:: " . $name . "\n\n";
1934 print "\n\n.. c:type:: " . $name . "\n\n";
1867 print " " . $args{'purpose'} . "\n\n";
1935 print_lineno($declaration_start_line);
1936 $lineprefix = " ";
1937 output_highlight_rst($args{'purpose'});
1938 print "\n";
1868
1939
1940 $lineprefix = $oldprefix;
1869 output_section_rst(@_);
1870}
1871
1872sub output_struct_rst(%) {
1873 my %args = %{$_[0]};
1874 my ($parameter);
1941 output_section_rst(@_);
1942}
1943
1944sub output_struct_rst(%) {
1945 my %args = %{$_[0]};
1946 my ($parameter);
1947 my $oldprefix = $lineprefix;
1875 my $name = $args{'type'} . " " . $args{'struct'};
1876
1877 print "\n\n.. c:type:: " . $name . "\n\n";
1948 my $name = $args{'type'} . " " . $args{'struct'};
1949
1950 print "\n\n.. c:type:: " . $name . "\n\n";
1878 print " " . $args{'purpose'} . "\n\n";
1951 print_lineno($declaration_start_line);
1952 $lineprefix = " ";
1953 output_highlight_rst($args{'purpose'});
1954 print "\n";
1879
1955
1880 print ":Definition:\n\n";
1881 print " ::\n\n";
1956 print "**Definition**\n\n";
1957 print "::\n\n";
1882 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1883 foreach $parameter (@{$args{'parameterlist'}}) {
1884 if ($parameter =~ /^#/) {
1958 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1959 foreach $parameter (@{$args{'parameterlist'}}) {
1960 if ($parameter =~ /^#/) {
1885 print " " . "$parameter\n";
1961 print " " . "$parameter\n";
1886 next;
1887 }
1888
1889 my $parameter_name = $parameter;
1890 $parameter_name =~ s/\[.*//;
1891
1892 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1893 $type = $args{'parametertypes'}{$parameter};

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

1898 # bitfield
1899 print " $1 $parameter$2;\n";
1900 } else {
1901 print " " . $type . " " . $parameter . ";\n";
1902 }
1903 }
1904 print " };\n\n";
1905
1962 next;
1963 }
1964
1965 my $parameter_name = $parameter;
1966 $parameter_name =~ s/\[.*//;
1967
1968 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1969 $type = $args{'parametertypes'}{$parameter};

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

1974 # bitfield
1975 print " $1 $parameter$2;\n";
1976 } else {
1977 print " " . $type . " " . $parameter . ";\n";
1978 }
1979 }
1980 print " };\n\n";
1981
1906 print ":Members:\n\n";
1982 print "**Members**\n\n";
1983 $lineprefix = " ";
1907 foreach $parameter (@{$args{'parameterlist'}}) {
1908 ($parameter =~ /^#/) && next;
1909
1910 my $parameter_name = $parameter;
1911 $parameter_name =~ s/\[.*//;
1912
1913 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1914 $type = $args{'parametertypes'}{$parameter};
1984 foreach $parameter (@{$args{'parameterlist'}}) {
1985 ($parameter =~ /^#/) && next;
1986
1987 my $parameter_name = $parameter;
1988 $parameter_name =~ s/\[.*//;
1989
1990 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1991 $type = $args{'parametertypes'}{$parameter};
1915 print " `$type $parameter`" . "\n";
1916 my $oldprefix = $lineprefix;
1917 $lineprefix = " ";
1992 print_lineno($parameterdesc_start_lines{$parameter_name});
1993 print "``$type $parameter``\n";
1918 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1994 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1919 $lineprefix = $oldprefix;
1920 print "\n";
1921 }
1922 print "\n";
1995 print "\n";
1996 }
1997 print "\n";
1998
1999 $lineprefix = $oldprefix;
1923 output_section_rst(@_);
1924}
1925
1926
1927## list mode output functions
1928
1929sub output_function_list(%) {
1930 my %args = %{$_[0]};

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

1964# generic output function for all types (function, struct/union, typedef, enum);
1965# calls the generated, variable output_ function name based on
1966# functype and output_mode
1967sub output_declaration {
1968 no strict 'refs';
1969 my $name = shift;
1970 my $functype = shift;
1971 my $func = "output_${functype}_$output_mode";
2000 output_section_rst(@_);
2001}
2002
2003
2004## list mode output functions
2005
2006sub output_function_list(%) {
2007 my %args = %{$_[0]};

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

2041# generic output function for all types (function, struct/union, typedef, enum);
2042# calls the generated, variable output_ function name based on
2043# functype and output_mode
2044sub output_declaration {
2045 no strict 'refs';
2046 my $name = shift;
2047 my $functype = shift;
2048 my $func = "output_${functype}_$output_mode";
1972 if (($function_only==0) ||
1973 ( $function_only == 1 && defined($function_table{$name})) ||
1974 ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
2049 if (($output_selection == OUTPUT_ALL) ||
2050 (($output_selection == OUTPUT_INCLUDE ||
2051 $output_selection == OUTPUT_EXPORTED) &&
2052 defined($function_table{$name})) ||
2053 (($output_selection == OUTPUT_EXCLUDE ||
2054 $output_selection == OUTPUT_INTERNAL) &&
2055 !($functype eq "function" && defined($function_table{$name}))))
1975 {
1976 &$func(@_);
1977 $section_counter++;
1978 }
1979}
1980
1981##
1982# generic output function - calls the right one based on current output mode.

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

2466 'sectionlist' => \@sectionlist,
2467 'sections' => \%sections,
2468 'purpose' => $declaration_purpose
2469 });
2470}
2471
2472sub reset_state {
2473 $function = "";
2056 {
2057 &$func(@_);
2058 $section_counter++;
2059 }
2060}
2061
2062##
2063# generic output function - calls the right one based on current output mode.

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

2547 'sectionlist' => \@sectionlist,
2548 'sections' => \%sections,
2549 'purpose' => $declaration_purpose
2550 });
2551}
2552
2553sub reset_state {
2554 $function = "";
2474 %constants = ();
2475 %parameterdescs = ();
2476 %parametertypes = ();
2477 @parameterlist = ();
2478 %sections = ();
2479 @sectionlist = ();
2480 $sectcheck = "";
2481 $struct_actual = "";
2482 $prototype = "";
2483
2555 %parameterdescs = ();
2556 %parametertypes = ();
2557 @parameterlist = ();
2558 %sections = ();
2559 @sectionlist = ();
2560 $sectcheck = "";
2561 $struct_actual = "";
2562 $prototype = "";
2563
2484 $state = 0;
2485 $split_doc_state = 0;
2564 $state = STATE_NORMAL;
2565 $inline_doc_state = STATE_INLINE_NA;
2486}
2487
2488sub tracepoint_munge($) {
2489 my $file = shift;
2490 my $tracepointname = 0;
2491 my $tracepointargs = 0;
2492
2493 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

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

2540 $count++;
2541 if ($count % 2 == 1) {
2542 substr($prototype, $ix, 1) = ' ';
2543 }
2544 }
2545 }
2546}
2547
2566}
2567
2568sub tracepoint_munge($) {
2569 my $file = shift;
2570 my $tracepointname = 0;
2571 my $tracepointargs = 0;
2572
2573 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

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

2620 $count++;
2621 if ($count % 2 == 1) {
2622 substr($prototype, $ix, 1) = ' ';
2623 }
2624 }
2625 }
2626}
2627
2548sub process_state3_function($$) {
2628sub process_proto_function($$) {
2549 my $x = shift;
2550 my $file = shift;
2551
2552 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2553
2554 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2555 # do nothing
2556 }

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

2570 {
2571 tracepoint_munge($file);
2572 }
2573 dump_function($prototype, $file);
2574 reset_state();
2575 }
2576}
2577
2629 my $x = shift;
2630 my $file = shift;
2631
2632 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2633
2634 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2635 # do nothing
2636 }

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

2650 {
2651 tracepoint_munge($file);
2652 }
2653 dump_function($prototype, $file);
2654 reset_state();
2655 }
2656}
2657
2578sub process_state3_type($$) {
2658sub process_proto_type($$) {
2579 my $x = shift;
2580 my $file = shift;
2581
2582 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2583 $x =~ s@^\s+@@gos; # strip leading spaces
2584 $x =~ s@\s+$@@gos; # strip trailing spaces
2585 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2586

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

2652sub process_file($) {
2653 my $file;
2654 my $identifier;
2655 my $func;
2656 my $descr;
2657 my $in_purpose = 0;
2658 my $initial_section_counter = $section_counter;
2659 my ($orig_file) = @_;
2659 my $x = shift;
2660 my $file = shift;
2661
2662 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2663 $x =~ s@^\s+@@gos; # strip leading spaces
2664 $x =~ s@\s+$@@gos; # strip trailing spaces
2665 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2666

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

2732sub process_file($) {
2733 my $file;
2734 my $identifier;
2735 my $func;
2736 my $descr;
2737 my $in_purpose = 0;
2738 my $initial_section_counter = $section_counter;
2739 my ($orig_file) = @_;
2740 my $leading_space;
2660
2661 if (defined($ENV{'SRCTREE'})) {
2662 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2663 }
2664 else {
2665 $file = $orig_file;
2666 }
2667 if (defined($source_map{$file})) {
2668 $file = $source_map{$file};
2669 }
2670
2671 if (!open(IN,"<$file")) {
2672 print STDERR "Error: Cannot open file $file\n";
2673 ++$errors;
2674 return;
2675 }
2676
2741
2742 if (defined($ENV{'SRCTREE'})) {
2743 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2744 }
2745 else {
2746 $file = $orig_file;
2747 }
2748 if (defined($source_map{$file})) {
2749 $file = $source_map{$file};
2750 }
2751
2752 if (!open(IN,"<$file")) {
2753 print STDERR "Error: Cannot open file $file\n";
2754 ++$errors;
2755 return;
2756 }
2757
2758 # two passes for -export and -internal
2759 if ($output_selection == OUTPUT_EXPORTED ||
2760 $output_selection == OUTPUT_INTERNAL) {
2761 while (<IN>) {
2762 if (/$export_symbol/o) {
2763 $function_table{$2} = 1;
2764 }
2765 }
2766 seek(IN, 0, 0);
2767 }
2768
2677 $. = 1;
2678
2679 $section_counter = 0;
2680 while (<IN>) {
2681 while (s/\\\s*$//) {
2682 $_ .= <IN>;
2683 }
2769 $. = 1;
2770
2771 $section_counter = 0;
2772 while (<IN>) {
2773 while (s/\\\s*$//) {
2774 $_ .= <IN>;
2775 }
2684 if ($state == 0) {
2776 if ($state == STATE_NORMAL) {
2685 if (/$doc_start/o) {
2777 if (/$doc_start/o) {
2686 $state = 1; # next line is always the function name
2778 $state = STATE_NAME; # next line is always the function name
2687 $in_doc_sect = 0;
2779 $in_doc_sect = 0;
2780 $declaration_start_line = $. + 1;
2688 }
2781 }
2689 } elsif ($state == 1) { # this line is the function name (always)
2782 } elsif ($state == STATE_NAME) {# this line is the function name (always)
2690 if (/$doc_block/o) {
2783 if (/$doc_block/o) {
2691 $state = 4;
2784 $state = STATE_DOCBLOCK;
2692 $contents = "";
2785 $contents = "";
2786 $new_start_line = $. + 1;
2787
2693 if ( $1 eq "" ) {
2694 $section = $section_intro;
2695 } else {
2696 $section = $1;
2697 }
2698 }
2699 elsif (/$doc_decl/o) {
2700 $identifier = $1;
2701 if (/\s*([\w\s]+?)\s*-/) {
2702 $identifier = $1;
2703 }
2704
2788 if ( $1 eq "" ) {
2789 $section = $section_intro;
2790 } else {
2791 $section = $1;
2792 }
2793 }
2794 elsif (/$doc_decl/o) {
2795 $identifier = $1;
2796 if (/\s*([\w\s]+?)\s*-/) {
2797 $identifier = $1;
2798 }
2799
2705 $state = 2;
2800 $state = STATE_FIELD;
2801 # if there's no @param blocks need to set up default section
2802 # here
2803 $contents = "";
2804 $section = $section_default;
2805 $new_start_line = $. + 1;
2706 if (/-(.*)/) {
2707 # strip leading/trailing/multiple spaces
2708 $descr= $1;
2709 $descr =~ s/^\s*//;
2710 $descr =~ s/\s*$//;
2711 $descr =~ s/\s+/ /g;
2712 $declaration_purpose = xml_escape($descr);
2713 $in_purpose = 1;

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

2735
2736 if ($verbose) {
2737 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2738 }
2739 } else {
2740 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2741 " - I thought it was a doc line\n";
2742 ++$warnings;
2806 if (/-(.*)/) {
2807 # strip leading/trailing/multiple spaces
2808 $descr= $1;
2809 $descr =~ s/^\s*//;
2810 $descr =~ s/\s*$//;
2811 $descr =~ s/\s+/ /g;
2812 $declaration_purpose = xml_escape($descr);
2813 $in_purpose = 1;

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

2835
2836 if ($verbose) {
2837 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2838 }
2839 } else {
2840 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2841 " - I thought it was a doc line\n";
2842 ++$warnings;
2743 $state = 0;
2843 $state = STATE_NORMAL;
2744 }
2844 }
2745 } elsif ($state == 2) { # look for head: lines, and include content
2746 if (/$doc_sect/o) {
2845 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2846 if (/$doc_sect/i) { # case insensitive for supported section names
2747 $newsection = $1;
2748 $newcontents = $2;
2749
2847 $newsection = $1;
2848 $newcontents = $2;
2849
2850 # map the supported section names to the canonical names
2851 if ($newsection =~ m/^description$/i) {
2852 $newsection = $section_default;
2853 } elsif ($newsection =~ m/^context$/i) {
2854 $newsection = $section_context;
2855 } elsif ($newsection =~ m/^returns?$/i) {
2856 $newsection = $section_return;
2857 } elsif ($newsection =~ m/^\@return$/) {
2858 # special: @return is a section, not a param description
2859 $newsection = $section_return;
2860 }
2861
2750 if (($contents ne "") && ($contents ne "\n")) {
2751 if (!$in_doc_sect && $verbose) {
2752 print STDERR "${file}:$.: warning: contents before sections\n";
2753 ++$warnings;
2754 }
2755 dump_section($file, $section, xml_escape($contents));
2756 $section = $section_default;
2757 }
2758
2759 $in_doc_sect = 1;
2760 $in_purpose = 0;
2761 $contents = $newcontents;
2862 if (($contents ne "") && ($contents ne "\n")) {
2863 if (!$in_doc_sect && $verbose) {
2864 print STDERR "${file}:$.: warning: contents before sections\n";
2865 ++$warnings;
2866 }
2867 dump_section($file, $section, xml_escape($contents));
2868 $section = $section_default;
2869 }
2870
2871 $in_doc_sect = 1;
2872 $in_purpose = 0;
2873 $contents = $newcontents;
2874 $new_start_line = $.;
2875 while ((substr($contents, 0, 1) eq " ") ||
2876 substr($contents, 0, 1) eq "\t") {
2877 $contents = substr($contents, 1);
2878 }
2762 if ($contents ne "") {
2879 if ($contents ne "") {
2763 while ((substr($contents, 0, 1) eq " ") ||
2764 substr($contents, 0, 1) eq "\t") {
2765 $contents = substr($contents, 1);
2766 }
2767 $contents .= "\n";
2768 }
2769 $section = $newsection;
2880 $contents .= "\n";
2881 }
2882 $section = $newsection;
2883 $leading_space = undef;
2770 } elsif (/$doc_end/) {
2771 if (($contents ne "") && ($contents ne "\n")) {
2772 dump_section($file, $section, xml_escape($contents));
2773 $section = $section_default;
2774 $contents = "";
2775 }
2776 # look for doc_com + <text> + doc_end:
2777 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2778 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2779 ++$warnings;
2780 }
2781
2782 $prototype = "";
2884 } elsif (/$doc_end/) {
2885 if (($contents ne "") && ($contents ne "\n")) {
2886 dump_section($file, $section, xml_escape($contents));
2887 $section = $section_default;
2888 $contents = "";
2889 }
2890 # look for doc_com + <text> + doc_end:
2891 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2892 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2893 ++$warnings;
2894 }
2895
2896 $prototype = "";
2783 $state = 3;
2897 $state = STATE_PROTO;
2784 $brcount = 0;
2785# print STDERR "end of doc comment, looking for prototype\n";
2786 } elsif (/$doc_content/) {
2787 # miguel-style comment kludge, look for blank lines after
2788 # @parameter line to signify start of description
2789 if ($1 eq "") {
2790 if ($section =~ m/^@/ || $section eq $section_context) {
2791 dump_section($file, $section, xml_escape($contents));
2792 $section = $section_default;
2793 $contents = "";
2898 $brcount = 0;
2899# print STDERR "end of doc comment, looking for prototype\n";
2900 } elsif (/$doc_content/) {
2901 # miguel-style comment kludge, look for blank lines after
2902 # @parameter line to signify start of description
2903 if ($1 eq "") {
2904 if ($section =~ m/^@/ || $section eq $section_context) {
2905 dump_section($file, $section, xml_escape($contents));
2906 $section = $section_default;
2907 $contents = "";
2908 $new_start_line = $.;
2794 } else {
2795 $contents .= "\n";
2796 }
2797 $in_purpose = 0;
2798 } elsif ($in_purpose == 1) {
2799 # Continued declaration purpose
2800 chomp($declaration_purpose);
2801 $declaration_purpose .= " " . xml_escape($1);
2802 $declaration_purpose =~ s/\s+/ /g;
2803 } else {
2909 } else {
2910 $contents .= "\n";
2911 }
2912 $in_purpose = 0;
2913 } elsif ($in_purpose == 1) {
2914 # Continued declaration purpose
2915 chomp($declaration_purpose);
2916 $declaration_purpose .= " " . xml_escape($1);
2917 $declaration_purpose =~ s/\s+/ /g;
2918 } else {
2804 $contents .= $1 . "\n";
2919 my $cont = $1;
2920 if ($section =~ m/^@/ || $section eq $section_context) {
2921 if (!defined $leading_space) {
2922 if ($cont =~ m/^(\s+)/) {
2923 $leading_space = $1;
2924 } else {
2925 $leading_space = "";
2926 }
2927 }
2928
2929 $cont =~ s/^$leading_space//;
2930 }
2931 $contents .= $cont . "\n";
2805 }
2806 } else {
2807 # i dont know - bad line? ignore.
2808 print STDERR "${file}:$.: warning: bad line: $_";
2809 ++$warnings;
2810 }
2932 }
2933 } else {
2934 # i dont know - bad line? ignore.
2935 print STDERR "${file}:$.: warning: bad line: $_";
2936 ++$warnings;
2937 }
2811 } elsif ($state == 5) { # scanning for split parameters
2938 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2812 # First line (state 1) needs to be a @parameter
2939 # First line (state 1) needs to be a @parameter
2813 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2940 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2814 $section = $1;
2815 $contents = $2;
2941 $section = $1;
2942 $contents = $2;
2943 $new_start_line = $.;
2816 if ($contents ne "") {
2817 while ((substr($contents, 0, 1) eq " ") ||
2818 substr($contents, 0, 1) eq "\t") {
2819 $contents = substr($contents, 1);
2820 }
2944 if ($contents ne "") {
2945 while ((substr($contents, 0, 1) eq " ") ||
2946 substr($contents, 0, 1) eq "\t") {
2947 $contents = substr($contents, 1);
2948 }
2821 $contents .= "\n";
2949 $contents .= "\n";
2822 }
2950 }
2823 $split_doc_state = 2;
2951 $inline_doc_state = STATE_INLINE_TEXT;
2824 # Documentation block end */
2952 # Documentation block end */
2825 } elsif (/$doc_split_end/) {
2953 } elsif (/$doc_inline_end/) {
2826 if (($contents ne "") && ($contents ne "\n")) {
2827 dump_section($file, $section, xml_escape($contents));
2828 $section = $section_default;
2829 $contents = "";
2830 }
2954 if (($contents ne "") && ($contents ne "\n")) {
2955 dump_section($file, $section, xml_escape($contents));
2956 $section = $section_default;
2957 $contents = "";
2958 }
2831 $state = 3;
2832 $split_doc_state = 0;
2959 $state = STATE_PROTO;
2960 $inline_doc_state = STATE_INLINE_NA;
2833 # Regular text
2834 } elsif (/$doc_content/) {
2961 # Regular text
2962 } elsif (/$doc_content/) {
2835 if ($split_doc_state == 2) {
2963 if ($inline_doc_state == STATE_INLINE_TEXT) {
2836 $contents .= $1 . "\n";
2964 $contents .= $1 . "\n";
2837 } elsif ($split_doc_state == 1) {
2838 $split_doc_state = 4;
2965 # nuke leading blank lines
2966 if ($contents =~ /^\s*$/) {
2967 $contents = "";
2968 }
2969 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2970 $inline_doc_state = STATE_INLINE_ERROR;
2839 print STDERR "Warning(${file}:$.): ";
2840 print STDERR "Incorrect use of kernel-doc format: $_";
2841 ++$warnings;
2842 }
2843 }
2971 print STDERR "Warning(${file}:$.): ";
2972 print STDERR "Incorrect use of kernel-doc format: $_";
2973 ++$warnings;
2974 }
2975 }
2844 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2845 if (/$doc_split_start/) {
2846 $state = 5;
2847 $split_doc_state = 1;
2976 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2977 if (/$doc_inline_start/) {
2978 $state = STATE_INLINE;
2979 $inline_doc_state = STATE_INLINE_NAME;
2848 } elsif ($decl_type eq 'function') {
2980 } elsif ($decl_type eq 'function') {
2849 process_state3_function($_, $file);
2981 process_proto_function($_, $file);
2850 } else {
2982 } else {
2851 process_state3_type($_, $file);
2983 process_proto_type($_, $file);
2852 }
2984 }
2853 } elsif ($state == 4) {
2854 # Documentation block
2855 if (/$doc_block/) {
2856 dump_doc_section($file, $section, xml_escape($contents));
2857 $contents = "";
2858 $function = "";
2859 %constants = ();
2860 %parameterdescs = ();
2861 %parametertypes = ();
2862 @parameterlist = ();
2863 %sections = ();
2864 @sectionlist = ();
2865 $prototype = "";
2866 if ( $1 eq "" ) {
2867 $section = $section_intro;
2868 } else {
2869 $section = $1;
2870 }
2871 }
2872 elsif (/$doc_end/)
2985 } elsif ($state == STATE_DOCBLOCK) {
2986 if (/$doc_end/)
2873 {
2874 dump_doc_section($file, $section, xml_escape($contents));
2987 {
2988 dump_doc_section($file, $section, xml_escape($contents));
2989 $section = $section_default;
2875 $contents = "";
2876 $function = "";
2990 $contents = "";
2991 $function = "";
2877 %constants = ();
2878 %parameterdescs = ();
2879 %parametertypes = ();
2880 @parameterlist = ();
2881 %sections = ();
2882 @sectionlist = ();
2883 $prototype = "";
2992 %parameterdescs = ();
2993 %parametertypes = ();
2994 @parameterlist = ();
2995 %sections = ();
2996 @sectionlist = ();
2997 $prototype = "";
2884 $state = 0;
2998 $state = STATE_NORMAL;
2885 }
2886 elsif (/$doc_content/)
2887 {
2888 if ( $1 eq "" )
2889 {
2890 $contents .= $blankline;
2891 }
2892 else
2893 {
2894 $contents .= $1 . "\n";
2895 }
2896 }
2897 }
2898 }
2899 if ($initial_section_counter == $section_counter) {
2900 print STDERR "${file}:1: warning: no structured comments found\n";
2999 }
3000 elsif (/$doc_content/)
3001 {
3002 if ( $1 eq "" )
3003 {
3004 $contents .= $blankline;
3005 }
3006 else
3007 {
3008 $contents .= $1 . "\n";
3009 }
3010 }
3011 }
3012 }
3013 if ($initial_section_counter == $section_counter) {
3014 print STDERR "${file}:1: warning: no structured comments found\n";
2901 if (($function_only == 1) && ($show_not_found == 1)) {
3015 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2902 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2903 }
2904 if ($output_mode eq "xml") {
2905 # The template wants at least one RefEntry here; make one.
2906 print "<refentry>\n";
2907 print " <refnamediv>\n";
2908 print " <refname>\n";
2909 print " ${orig_file}\n";

--- 62 unchanged lines hidden --- 		3016 print STDERR " Was looking for '$_'.\n" for keys %function_table;
3017 }
3018 if ($output_mode eq "xml") {
3019 # The template wants at least one RefEntry here; make one.
3020 print "<refentry>\n";
3021 print " <refnamediv>\n";
3022 print " <refname>\n";
3023 print " ${orig_file}\n";

--- 62 unchanged lines hidden ---