kernel-doc (5599617ec0719dba3b1f85a4abca2a6c93368ae3) kernel-doc (ebff7f929b2a72fa614f5e95fd34c56c82ac9c36)
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:

--- 131 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]+)';
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:

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

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

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

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

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

301
302my $verbose = 0;
303my $output_mode = "man";
304my $output_preformatted = 0;
305my $no_doc_sections = 0;
306my @highlights = @highlights_man;
307my $blankline = $blankline_man;
308my $modulename = "Kernel API";
297 [$type_param, "**\$1**"]
298 );
299my $blankline_rst = "\n";
300
301# list mode
302my @highlights_list = (
303 [$type_constant, "\$1"],
304 [$type_func, "\$1"],

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

317
318my $verbose = 0;
319my $output_mode = "man";
320my $output_preformatted = 0;
321my $no_doc_sections = 0;
322my @highlights = @highlights_man;
323my $blankline = $blankline_man;
324my $modulename = "Kernel API";
309my $function_only = 0;
325
326use constant {
327 OUTPUT_ALL => 0, # output all symbols and doc sections
328 OUTPUT_INCLUDE => 1, # output only specified symbols
329 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
330 OUTPUT_EXPORTED => 3, # output exported symbols
331 OUTPUT_INTERNAL => 4, # output non-exported symbols
332};
333my $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;

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

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
334my $show_not_found = 0;
335
336my @build_time;
337if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
338 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
339 @build_time = gmtime($seconds);
340} else {
341 @build_time = localtime;

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

363# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
364# We keep track of number of generated entries and generate a dummy
365# if needs be to ensure the expanded template can be postprocessed
366# into html.
367my $section_counter = 0;
368
369my $lineprefix="";
370
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
371# Parser states
372use constant {
373 STATE_NORMAL => 0, # normal code
374 STATE_NAME => 1, # looking for function name
375 STATE_FIELD => 2, # scanning field start
376 STATE_PROTO => 3, # scanning prototype
377 STATE_DOCBLOCK => 4, # documentation block
378 STATE_INLINE => 5, # gathering documentation outside main block
379};
354my $state;
355my $in_doc_sect;
356
380my $state;
381my $in_doc_sect;
382
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;
383# Inline documentation state
384use constant {
385 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
386 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
387 STATE_INLINE_TEXT => 2, # looking for member documentation
388 STATE_INLINE_END => 3, # done
389 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
390 # Spit a warning as it's not
391 # proper kernel-doc and ignore the rest.
392};
393my $inline_doc_state;
365
366#declaration types: can be
367# 'function', 'struct', 'union', 'enum', 'typedef'
368my $decl_type;
369
394
395#declaration types: can be
396# 'function', 'struct', 'union', 'enum', 'typedef'
397my $decl_type;
398
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+)';
399my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
400my $doc_end = '\*/';
401my $doc_com = '\s*\*\s*';
402my $doc_com_body = '\s*\* ?';
403my $doc_decl = $doc_com . '(\w+)';
377my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
404# @params and a strictly limited set of supported section names
405my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)';
378my $doc_content = $doc_com_body . '(.*)';
379my $doc_block = $doc_com . 'DOC:\s*(.*)?';
406my $doc_content = $doc_com_body . '(.*)';
407my $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*$';
408my $doc_inline_start = '^\s*/\*\*\s*$';
409my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
410my $doc_inline_end = '^\s*\*/\s*$';
411my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
383
412
384my %constants;
385my %parameterdescs;
386my @parameterlist;
387my %sections;
388my @sectionlist;
389my $sectcheck;
390my $struct_actual;
391
392my $contents = "";
413my %parameterdescs;
414my @parameterlist;
415my %sections;
416my @sectionlist;
417my $sectcheck;
418my $struct_actual;
419
420my $contents = "";
421
422# 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
423my $section_default = "Description"; # default section
424my $section_intro = "Introduction";
425my $section = $section_default;
426my $section_context = "Context";
427my $section_return = "Return";
428
429my $undescribed = "-- undescribed --";
430

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

462 $blankline = $blankline_list;
463 } elsif ($cmd eq "-gnome") {
464 $output_mode = "gnome";
465 @highlights = @highlights_gnome;
466 $blankline = $blankline_gnome;
467 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
468 $modulename = shift @ARGV;
469 } elsif ($cmd eq "-function") { # to only output specific functions
440 $function_only = 1;
470 $output_selection = OUTPUT_INCLUDE;
441 $function = shift @ARGV;
442 $function_table{$function} = 1;
471 $function = shift @ARGV;
472 $function_table{$function} = 1;
443 } elsif ($cmd eq "-nofunction") { # to only output specific functions
444 $function_only = 2;
473 } elsif ($cmd eq "-nofunction") { # output all except specific functions
474 $output_selection = OUTPUT_EXCLUDE;
445 $function = shift @ARGV;
446 $function_table{$function} = 1;
475 $function = shift @ARGV;
476 $function_table{$function} = 1;
477 } elsif ($cmd eq "-export") { # only exported symbols
478 $output_selection = OUTPUT_EXPORTED;
479 %function_table = ()
480 } elsif ($cmd eq "-internal") { # only non-exported symbols
481 $output_selection = OUTPUT_INTERNAL;
482 %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;
453 } elsif ($cmd eq '-show-not-found') {
454 $show_not_found = 1;

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

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
483 } elsif ($cmd eq "-v") {
484 $verbose = 1;
485 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
486 usage();
487 } elsif ($cmd eq '-no-doc-sections') {
488 $no_doc_sections = 1;
489 } elsif ($cmd eq '-show-not-found') {
490 $show_not_found = 1;

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

506##
507# dumps section contents to arrays/hashes intended for that purpose.
508#
509sub dump_section {
510 my $file = shift;
511 my $name = shift;
512 my $contents = join "\n", @_;
513
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/) {
514 if ($name =~ m/$type_param/) {
483# print STDERR "parameter def '$1' = '$contents'\n";
484 $name = $1;
485 $parameterdescs{$name} = $contents;
486 $sectcheck = $sectcheck . $name . " ";
487 } elsif ($name eq "@\.\.\.") {
488# print STDERR "parameter def '...' = '$contents'\n";
489 $name = "...";
490 $parameterdescs{$name} = $contents;
491 $sectcheck = $sectcheck . $name . " ";
492 } else {
493# print STDERR "other section '$name' = '$contents'\n";
494 if (defined($sections{$name}) && ($sections{$name} ne "")) {
515# print STDERR "parameter def '$1' = '$contents'\n";
516 $name = $1;
517 $parameterdescs{$name} = $contents;
518 $sectcheck = $sectcheck . $name . " ";
519 } elsif ($name eq "@\.\.\.") {
520# print STDERR "parameter def '...' = '$contents'\n";
521 $name = "...";
522 $parameterdescs{$name} = $contents;
523 $sectcheck = $sectcheck . $name . " ";
524 } else {
525# print STDERR "other section '$name' = '$contents'\n";
526 if (defined($sections{$name}) && ($sections{$name} ne "")) {
495 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
496 ++$errors;
527 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
528 ++$warnings;
529 $sections{$name} .= $contents;
530 } else {
531 $sections{$name} = $contents;
532 push @sectionlist, $name;
497 }
533 }
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
534 }
535}
536
537##
538# dump DOC: section after checking that it should go out
539#
540sub dump_doc_section {
541 my $file = shift;
542 my $name = shift;
543 my $contents = join "\n", @_;
544
545 if ($no_doc_sections) {
546 return;
547 }
548
515 if (($function_only == 0) ||
516 ( $function_only == 1 && defined($function_table{$name})) ||
517 ( $function_only == 2 && !defined($function_table{$name})))
549 if (($output_selection == OUTPUT_ALL) ||
550 ($output_selection == OUTPUT_INCLUDE &&
551 defined($function_table{$name})) ||
552 ($output_selection == OUTPUT_EXCLUDE &&
553 !defined($function_table{$name})))
518 {
519 dump_section($file, $name, $contents);
520 output_blockhead({'sectionlist' => \@sectionlist,
521 'sections' => \%sections,
522 'module' => $modulename,
554 {
555 dump_section($file, $name, $contents);
556 output_blockhead({'sectionlist' => \@sectionlist,
557 'sections' => \%sections,
558 'module' => $modulename,
523 'content-only' => ($function_only != 0), });
559 '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'}}) {
560 }
561}
562
563##
564# output function
565#
566# parameterdescs, a hash.
567# function => "function name"

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

1767# starts by putting out the name of the doc section itself, but that tends
1768# to duplicate a header already in the template file.
1769#
1770sub output_blockhead_rst(%) {
1771 my %args = %{$_[0]};
1772 my ($parameter, $section);
1773
1774 foreach $section (@{$args{'sectionlist'}}) {
1739 print "**$section**\n\n";
1775 if ($output_selection != OUTPUT_INCLUDE) {
1776 print "**$section**\n\n";
1777 }
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) {
1778 output_highlight_rst($args{'sections'}{$section});
1779 print "\n";
1780 }
1781}
1782
1783sub output_highlight_rst {
1784 my $contents = join "\n",@_;
1785 my $line;
1786
1787 # undo the evil effects of xml_escape() earlier
1788 $contents = xml_unescape($contents);
1789
1790 eval $dohighlight;
1791 die $@ if $@;
1792
1793 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";
1794 print $lineprefix . $line . "\n";
1763 }
1764}
1765
1766sub output_function_rst(%) {
1767 my %args = %{$_[0]};
1768 my ($parameter, $section);
1795 }
1796}
1797
1798sub output_function_rst(%) {
1799 my %args = %{$_[0]};
1800 my ($parameter, $section);
1801 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 }
1802 my $start;
1803
1804 print ".. c:function:: ";
1805 if ($args{'functiontype'} ne "") {
1806 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1807 } else {
1808 $start = $args{'function'} . " (";
1809 }

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

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

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

1943 # bitfield
1944 print " $1 $parameter$2;\n";
1945 } else {
1946 print " " . $type . " " . $parameter . ";\n";
1947 }
1948 }
1949 print " };\n\n";
1950
1906 print ":Members:\n\n";
1951 print "**Members**\n\n";
1952 $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};
1953 foreach $parameter (@{$args{'parameterlist'}}) {
1954 ($parameter =~ /^#/) && next;
1955
1956 my $parameter_name = $parameter;
1957 $parameter_name =~ s/\[.*//;
1958
1959 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1960 $type = $args{'parametertypes'}{$parameter};
1915 print " `$type $parameter`" . "\n";
1916 my $oldprefix = $lineprefix;
1917 $lineprefix = " ";
1961 print "``$type $parameter``\n";
1918 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1962 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1919 $lineprefix = $oldprefix;
1920 print "\n";
1921 }
1922 print "\n";
1963 print "\n";
1964 }
1965 print "\n";
1966
1967 $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";
1968 output_section_rst(@_);
1969}
1970
1971
1972## list mode output functions
1973
1974sub output_function_list(%) {
1975 my %args = %{$_[0]};

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

2009# generic output function for all types (function, struct/union, typedef, enum);
2010# calls the generated, variable output_ function name based on
2011# functype and output_mode
2012sub output_declaration {
2013 no strict 'refs';
2014 my $name = shift;
2015 my $functype = shift;
2016 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}))))
2017 if (($output_selection == OUTPUT_ALL) ||
2018 (($output_selection == OUTPUT_INCLUDE ||
2019 $output_selection == OUTPUT_EXPORTED) &&
2020 defined($function_table{$name})) ||
2021 (($output_selection == OUTPUT_EXCLUDE ||
2022 $output_selection == OUTPUT_INTERNAL) &&
2023 !($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 = "";
2024 {
2025 &$func(@_);
2026 $section_counter++;
2027 }
2028}
2029
2030##
2031# generic output function - calls the right one based on current output mode.

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

2515 'sectionlist' => \@sectionlist,
2516 'sections' => \%sections,
2517 'purpose' => $declaration_purpose
2518 });
2519}
2520
2521sub reset_state {
2522 $function = "";
2474 %constants = ();
2475 %parameterdescs = ();
2476 %parametertypes = ();
2477 @parameterlist = ();
2478 %sections = ();
2479 @sectionlist = ();
2480 $sectcheck = "";
2481 $struct_actual = "";
2482 $prototype = "";
2483
2523 %parameterdescs = ();
2524 %parametertypes = ();
2525 @parameterlist = ();
2526 %sections = ();
2527 @sectionlist = ();
2528 $sectcheck = "";
2529 $struct_actual = "";
2530 $prototype = "";
2531
2484 $state = 0;
2485 $split_doc_state = 0;
2532 $state = STATE_NORMAL;
2533 $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\((.*?),/) {

--- 158 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) = @_;
2534}
2535
2536sub tracepoint_munge($) {
2537 my $file = shift;
2538 my $tracepointname = 0;
2539 my $tracepointargs = 0;
2540
2541 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

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

2700sub process_file($) {
2701 my $file;
2702 my $identifier;
2703 my $func;
2704 my $descr;
2705 my $in_purpose = 0;
2706 my $initial_section_counter = $section_counter;
2707 my ($orig_file) = @_;
2708 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
2709
2710 if (defined($ENV{'SRCTREE'})) {
2711 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2712 }
2713 else {
2714 $file = $orig_file;
2715 }
2716 if (defined($source_map{$file})) {
2717 $file = $source_map{$file};
2718 }
2719
2720 if (!open(IN,"<$file")) {
2721 print STDERR "Error: Cannot open file $file\n";
2722 ++$errors;
2723 return;
2724 }
2725
2726 # two passes for -export and -internal
2727 if ($output_selection == OUTPUT_EXPORTED ||
2728 $output_selection == OUTPUT_INTERNAL) {
2729 while (<IN>) {
2730 if (/$export_symbol/o) {
2731 $function_table{$2} = 1;
2732 }
2733 }
2734 seek(IN, 0, 0);
2735 }
2736
2677 $. = 1;
2678
2679 $section_counter = 0;
2680 while (<IN>) {
2681 while (s/\\\s*$//) {
2682 $_ .= <IN>;
2683 }
2737 $. = 1;
2738
2739 $section_counter = 0;
2740 while (<IN>) {
2741 while (s/\\\s*$//) {
2742 $_ .= <IN>;
2743 }
2684 if ($state == 0) {
2744 if ($state == STATE_NORMAL) {
2685 if (/$doc_start/o) {
2745 if (/$doc_start/o) {
2686 $state = 1; # next line is always the function name
2746 $state = STATE_NAME; # next line is always the function name
2687 $in_doc_sect = 0;
2688 }
2747 $in_doc_sect = 0;
2748 }
2689 } elsif ($state == 1) { # this line is the function name (always)
2749 } elsif ($state == STATE_NAME) {# this line is the function name (always)
2690 if (/$doc_block/o) {
2750 if (/$doc_block/o) {
2691 $state = 4;
2751 $state = STATE_DOCBLOCK;
2692 $contents = "";
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
2752 $contents = "";
2753 if ( $1 eq "" ) {
2754 $section = $section_intro;
2755 } else {
2756 $section = $1;
2757 }
2758 }
2759 elsif (/$doc_decl/o) {
2760 $identifier = $1;
2761 if (/\s*([\w\s]+?)\s*-/) {
2762 $identifier = $1;
2763 }
2764
2705 $state = 2;
2765 $state = STATE_FIELD;
2766 $contents = "";
2767 $section = $section_default;
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;
2768 if (/-(.*)/) {
2769 # strip leading/trailing/multiple spaces
2770 $descr= $1;
2771 $descr =~ s/^\s*//;
2772 $descr =~ s/\s*$//;
2773 $descr =~ s/\s+/ /g;
2774 $declaration_purpose = xml_escape($descr);
2775 $in_purpose = 1;

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

2797
2798 if ($verbose) {
2799 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2800 }
2801 } else {
2802 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2803 " - I thought it was a doc line\n";
2804 ++$warnings;
2743 $state = 0;
2805 $state = STATE_NORMAL;
2744 }
2806 }
2745 } elsif ($state == 2) { # look for head: lines, and include content
2746 if (/$doc_sect/o) {
2807 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2808 if (/$doc_sect/i) { # case insensitive for supported section names
2747 $newsection = $1;
2748 $newcontents = $2;
2749
2809 $newsection = $1;
2810 $newcontents = $2;
2811
2812 # map the supported section names to the canonical names
2813 if ($newsection =~ m/^description$/i) {
2814 $newsection = $section_default;
2815 } elsif ($newsection =~ m/^context$/i) {
2816 $newsection = $section_context;
2817 } elsif ($newsection =~ m/^returns?$/i) {
2818 $newsection = $section_return;
2819 } elsif ($newsection =~ m/^\@return$/) {
2820 # special: @return is a section, not a param description
2821 $newsection = $section_return;
2822 }
2823
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;
2824 if (($contents ne "") && ($contents ne "\n")) {
2825 if (!$in_doc_sect && $verbose) {
2826 print STDERR "${file}:$.: warning: contents before sections\n";
2827 ++$warnings;
2828 }
2829 dump_section($file, $section, xml_escape($contents));
2830 $section = $section_default;
2831 }
2832
2833 $in_doc_sect = 1;
2834 $in_purpose = 0;
2835 $contents = $newcontents;
2836 while ((substr($contents, 0, 1) eq " ") ||
2837 substr($contents, 0, 1) eq "\t") {
2838 $contents = substr($contents, 1);
2839 }
2762 if ($contents ne "") {
2840 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;
2841 $contents .= "\n";
2842 }
2843 $section = $newsection;
2844 $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 = "";
2845 } elsif (/$doc_end/) {
2846 if (($contents ne "") && ($contents ne "\n")) {
2847 dump_section($file, $section, xml_escape($contents));
2848 $section = $section_default;
2849 $contents = "";
2850 }
2851 # look for doc_com + <text> + doc_end:
2852 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2853 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2854 ++$warnings;
2855 }
2856
2857 $prototype = "";
2783 $state = 3;
2858 $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));

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

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 {
2859 $brcount = 0;
2860# print STDERR "end of doc comment, looking for prototype\n";
2861 } elsif (/$doc_content/) {
2862 # miguel-style comment kludge, look for blank lines after
2863 # @parameter line to signify start of description
2864 if ($1 eq "") {
2865 if ($section =~ m/^@/ || $section eq $section_context) {
2866 dump_section($file, $section, xml_escape($contents));

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

2871 }
2872 $in_purpose = 0;
2873 } elsif ($in_purpose == 1) {
2874 # Continued declaration purpose
2875 chomp($declaration_purpose);
2876 $declaration_purpose .= " " . xml_escape($1);
2877 $declaration_purpose =~ s/\s+/ /g;
2878 } else {
2804 $contents .= $1 . "\n";
2879 my $cont = $1;
2880 if ($section =~ m/^@/ || $section eq $section_context) {
2881 if (!defined $leading_space) {
2882 if ($cont =~ m/^(\s+)/) {
2883 $leading_space = $1;
2884 } else {
2885 $leading_space = "";
2886 }
2887 }
2888
2889 $cont =~ s/^$leading_space//;
2890 }
2891 $contents .= $cont . "\n";
2805 }
2806 } else {
2807 # i dont know - bad line? ignore.
2808 print STDERR "${file}:$.: warning: bad line: $_";
2809 ++$warnings;
2810 }
2892 }
2893 } else {
2894 # i dont know - bad line? ignore.
2895 print STDERR "${file}:$.: warning: bad line: $_";
2896 ++$warnings;
2897 }
2811 } elsif ($state == 5) { # scanning for split parameters
2898 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2812 # First line (state 1) needs to be a @parameter
2899 # First line (state 1) needs to be a @parameter
2813 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2900 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2814 $section = $1;
2815 $contents = $2;
2816 if ($contents ne "") {
2817 while ((substr($contents, 0, 1) eq " ") ||
2818 substr($contents, 0, 1) eq "\t") {
2819 $contents = substr($contents, 1);
2820 }
2901 $section = $1;
2902 $contents = $2;
2903 if ($contents ne "") {
2904 while ((substr($contents, 0, 1) eq " ") ||
2905 substr($contents, 0, 1) eq "\t") {
2906 $contents = substr($contents, 1);
2907 }
2821 $contents .= "\n";
2908 $contents .= "\n";
2822 }
2909 }
2823 $split_doc_state = 2;
2910 $inline_doc_state = STATE_INLINE_TEXT;
2824 # Documentation block end */
2911 # Documentation block end */
2825 } elsif (/$doc_split_end/) {
2912 } 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 }
2913 if (($contents ne "") && ($contents ne "\n")) {
2914 dump_section($file, $section, xml_escape($contents));
2915 $section = $section_default;
2916 $contents = "";
2917 }
2831 $state = 3;
2832 $split_doc_state = 0;
2918 $state = STATE_PROTO;
2919 $inline_doc_state = STATE_INLINE_NA;
2833 # Regular text
2834 } elsif (/$doc_content/) {
2920 # Regular text
2921 } elsif (/$doc_content/) {
2835 if ($split_doc_state == 2) {
2922 if ($inline_doc_state == STATE_INLINE_TEXT) {
2836 $contents .= $1 . "\n";
2923 $contents .= $1 . "\n";
2837 } elsif ($split_doc_state == 1) {
2838 $split_doc_state = 4;
2924 # nuke leading blank lines
2925 if ($contents =~ /^\s*$/) {
2926 $contents = "";
2927 }
2928 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2929 $inline_doc_state = STATE_INLINE_ERROR;
2839 print STDERR "Warning(${file}:$.): ";
2840 print STDERR "Incorrect use of kernel-doc format: $_";
2841 ++$warnings;
2842 }
2843 }
2930 print STDERR "Warning(${file}:$.): ";
2931 print STDERR "Incorrect use of kernel-doc format: $_";
2932 ++$warnings;
2933 }
2934 }
2844 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2845 if (/$doc_split_start/) {
2846 $state = 5;
2847 $split_doc_state = 1;
2935 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2936 if (/$doc_inline_start/) {
2937 $state = STATE_INLINE;
2938 $inline_doc_state = STATE_INLINE_NAME;
2848 } elsif ($decl_type eq 'function') {
2849 process_state3_function($_, $file);
2850 } else {
2851 process_state3_type($_, $file);
2852 }
2939 } elsif ($decl_type eq 'function') {
2940 process_state3_function($_, $file);
2941 } else {
2942 process_state3_type($_, $file);
2943 }
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/)
2944 } elsif ($state == STATE_DOCBLOCK) {
2945 if (/$doc_end/)
2873 {
2874 dump_doc_section($file, $section, xml_escape($contents));
2946 {
2947 dump_doc_section($file, $section, xml_escape($contents));
2948 $section = $section_default;
2875 $contents = "";
2876 $function = "";
2949 $contents = "";
2950 $function = "";
2877 %constants = ();
2878 %parameterdescs = ();
2879 %parametertypes = ();
2880 @parameterlist = ();
2881 %sections = ();
2882 @sectionlist = ();
2883 $prototype = "";
2951 %parameterdescs = ();
2952 %parametertypes = ();
2953 @parameterlist = ();
2954 %sections = ();
2955 @sectionlist = ();
2956 $prototype = "";
2884 $state = 0;
2957 $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";
2958 }
2959 elsif (/$doc_content/)
2960 {
2961 if ( $1 eq "" )
2962 {
2963 $contents .= $blankline;
2964 }
2965 else
2966 {
2967 $contents .= $1 . "\n";
2968 }
2969 }
2970 }
2971 }
2972 if ($initial_section_counter == $section_counter) {
2973 print STDERR "${file}:1: warning: no structured comments found\n";
2901 if (($function_only == 1) && ($show_not_found == 1)) {
2974 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 --- 		2975 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2976 }
2977 if ($output_mode eq "xml") {
2978 # The template wants at least one RefEntry here; make one.
2979 print "<refentry>\n";
2980 print " <refnamediv>\n";
2981 print " <refname>\n";
2982 print " ${orig_file}\n";

--- 62 unchanged lines hidden ---