kernel-doc (c6380ecd8e9bee7aba3d9a5a94b58168244c4a61) kernel-doc (0891f959935203e6c0e6c3e62968da56eedba6bf)
1#!/usr/bin/env perl
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
2
3use warnings;
4use strict;
5
6## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
7## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
8## Copyright (C) 2001 Simon Huggins ##
9## Copyright (C) 2005-2012 Randy Dunlap ##

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

323my $section_counter = 0;
324
325my $lineprefix="";
326
327# Parser states
328use constant {
329 STATE_NORMAL => 0, # normal code
330 STATE_NAME => 1, # looking for function name
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
9## Copyright (C) 2001 Simon Huggins ##
10## Copyright (C) 2005-2012 Randy Dunlap ##

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

324my $section_counter = 0;
325
326my $lineprefix="";
327
328# Parser states
329use constant {
330 STATE_NORMAL => 0, # normal code
331 STATE_NAME => 1, # looking for function name
331 STATE_FIELD => 2, # scanning field start
332 STATE_PROTO => 3, # scanning prototype
333 STATE_DOCBLOCK => 4, # documentation block
334 STATE_INLINE => 5, # gathering documentation outside main block
332 STATE_BODY_MAYBE => 2, # body - or maybe more description
333 STATE_BODY => 3, # the body of the comment
334 STATE_PROTO => 4, # scanning prototype
335 STATE_DOCBLOCK => 5, # documentation block
336 STATE_INLINE => 6, # gathering documentation outside main block
335};
336my $state;
337my $in_doc_sect;
337};
338my $state;
339my $in_doc_sect;
340my $leading_space;
338
339# Inline documentation state
340use constant {
341 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
342 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
343 STATE_INLINE_TEXT => 2, # looking for member documentation
344 STATE_INLINE_END => 3, # done
345 STATE_INLINE_ERROR => 4, # error - Comment without header was found.

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

358my $doc_com_body = '\s*\* ?';
359my $doc_decl = $doc_com . '(\w+)';
360# @params and a strictly limited set of supported section names
361my $doc_sect = $doc_com .
362 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
363my $doc_content = $doc_com_body . '(.*)';
364my $doc_block = $doc_com . 'DOC:\s*(.*)?';
365my $doc_inline_start = '^\s*/\*\*\s*$';
341
342# Inline documentation state
343use constant {
344 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
345 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
346 STATE_INLINE_TEXT => 2, # looking for member documentation
347 STATE_INLINE_END => 3, # done
348 STATE_INLINE_ERROR => 4, # error - Comment without header was found.

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

361my $doc_com_body = '\s*\* ?';
362my $doc_decl = $doc_com . '(\w+)';
363# @params and a strictly limited set of supported section names
364my $doc_sect = $doc_com .
365 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
366my $doc_content = $doc_com_body . '(.*)';
367my $doc_block = $doc_com . 'DOC:\s*(.*)?';
368my $doc_inline_start = '^\s*/\*\*\s*$';
366my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
369my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
367my $doc_inline_end = '^\s*\*/\s*$';
368my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
369my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
370
371my %parameterdescs;
372my %parameterdesc_start_lines;
373my @parameterlist;
374my %sections;

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

548# print STDERR "contents af:$contents\n";
549
550 foreach $line (split "\n", $contents) {
551 if (! $output_preformatted) {
552 $line =~ s/^\s*//;
553 }
554 if ($line eq ""){
555 if (! $output_preformatted) {
370my $doc_inline_end = '^\s*\*/\s*$';
371my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
372my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
373
374my %parameterdescs;
375my %parameterdesc_start_lines;
376my @parameterlist;
377my %sections;

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

551# print STDERR "contents af:$contents\n";
552
553 foreach $line (split "\n", $contents) {
554 if (! $output_preformatted) {
555 $line =~ s/^\s*//;
556 }
557 if ($line eq ""){
558 if (! $output_preformatted) {
556 print $lineprefix, local_unescape($blankline);
559 print $lineprefix, $blankline;
557 }
558 } else {
560 }
561 } else {
559 $line =~ s/\\\\\\/\&/g;
560 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
561 print "\\&$line";
562 } else {
563 print $lineprefix, $line;
564 }
565 }
566 print "\n";
567 }

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

742 print "**$section**\n\n";
743 }
744 print_lineno($section_start_lines{$section});
745 output_highlight_rst($args{'sections'}{$section});
746 print "\n";
747 }
748}
749
562 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
563 print "\\&$line";
564 } else {
565 print $lineprefix, $line;
566 }
567 }
568 print "\n";
569 }

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

744 print "**$section**\n\n";
745 }
746 print_lineno($section_start_lines{$section});
747 output_highlight_rst($args{'sections'}{$section});
748 print "\n";
749 }
750}
751
752#
753# Apply the RST highlights to a sub-block of text.
754#
755sub highlight_block($) {
756 # The dohighlight kludge requires the text be called $contents
757 my $contents = shift;
758 eval $dohighlight;
759 die $@ if $@;
760 return $contents;
761}
762
763#
764# Regexes used only here.
765#
766my $sphinx_literal = '^[^.].*::$';
767my $sphinx_cblock = '^\.\.\ +code-block::';
768
750sub output_highlight_rst {
769sub output_highlight_rst {
751 my $contents = join "\n",@_;
770 my $input = join "\n",@_;
771 my $output = "";
752 my $line;
772 my $line;
773 my $in_literal = 0;
774 my $litprefix;
775 my $block = "";
753
776
754 # undo the evil effects of xml_escape() earlier
755 $contents = xml_unescape($contents);
777 foreach $line (split "\n",$input) {
778 #
779 # If we're in a literal block, see if we should drop out
780 # of it. Otherwise pass the line straight through unmunged.
781 #
782 if ($in_literal) {
783 if (! ($line =~ /^\s*$/)) {
784 #
785 # If this is the first non-blank line in a literal
786 # block we need to figure out what the proper indent is.
787 #
788 if ($litprefix eq "") {
789 $line =~ /^(\s*)/;
790 $litprefix = '^' . $1;
791 $output .= $line . "\n";
792 } elsif (! ($line =~ /$litprefix/)) {
793 $in_literal = 0;
794 } else {
795 $output .= $line . "\n";
796 }
797 } else {
798 $output .= $line . "\n";
799 }
800 }
801 #
802 # Not in a literal block (or just dropped out)
803 #
804 if (! $in_literal) {
805 $block .= $line . "\n";
806 if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
807 $in_literal = 1;
808 $litprefix = "";
809 $output .= highlight_block($block);
810 $block = ""
811 }
812 }
813 }
756
814
757 eval $dohighlight;
758 die $@ if $@;
759
760 foreach $line (split "\n", $contents) {
815 if ($block) {
816 $output .= highlight_block($block);
817 }
818 foreach $line (split "\n", $output) {
761 print $lineprefix . $line . "\n";
762 }
763}
764
765sub output_function_rst(%) {
766 my %args = %{$_[0]};
767 my ($parameter, $section);
768 my $oldprefix = $lineprefix;

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

1417
1418 if (show_warnings($type, $declaration_name)) {
1419 print STDERR
1420 "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1421 ++$warnings;
1422 }
1423 }
1424
819 print $lineprefix . $line . "\n";
820 }
821}
822
823sub output_function_rst(%) {
824 my %args = %{$_[0]};
825 my ($parameter, $section);
826 my $oldprefix = $lineprefix;

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

1475
1476 if (show_warnings($type, $declaration_name)) {
1477 print STDERR
1478 "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1479 ++$warnings;
1480 }
1481 }
1482
1425 $param = xml_escape($param);
1426
1427 # strip spaces from $param so that it is one continuous string
1428 # on @parameterlist;
1429 # this fixes a problem where check_sections() cannot find
1430 # a parameter like "addr[6 + 2]" because it actually appears
1431 # as "addr[6", "+", "2]" on the parameter list;
1432 # but it's better to maintain the param string unchanged for output,
1433 # so just weaken the string compare in check_sections() to ignore
1434 # "[blah" in a parameter string;

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

1517 $prototype =~ s/^__inline +//;
1518 $prototype =~ s/^__always_inline +//;
1519 $prototype =~ s/^noinline +//;
1520 $prototype =~ s/__init +//;
1521 $prototype =~ s/__init_or_module +//;
1522 $prototype =~ s/__meminit +//;
1523 $prototype =~ s/__must_check +//;
1524 $prototype =~ s/__weak +//;
1483 # strip spaces from $param so that it is one continuous string
1484 # on @parameterlist;
1485 # this fixes a problem where check_sections() cannot find
1486 # a parameter like "addr[6 + 2]" because it actually appears
1487 # as "addr[6", "+", "2]" on the parameter list;
1488 # but it's better to maintain the param string unchanged for output,
1489 # so just weaken the string compare in check_sections() to ignore
1490 # "[blah" in a parameter string;

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

1573 $prototype =~ s/^__inline +//;
1574 $prototype =~ s/^__always_inline +//;
1575 $prototype =~ s/^noinline +//;
1576 $prototype =~ s/__init +//;
1577 $prototype =~ s/__init_or_module +//;
1578 $prototype =~ s/__meminit +//;
1579 $prototype =~ s/__must_check +//;
1580 $prototype =~ s/__weak +//;
1581 $prototype =~ s/__sched +//;
1525 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1526 $prototype =~ s/__attribute__\s*\(\(
1527 (?:
1528 [\w\s]++ # attribute name
1529 (?:\([^)]*+\))? # attribute arguments
1530 \s*+,? # optional comma at the end
1531 )+
1532 \)\)\s+//x;

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

1743 $x = $3;
1744 } else {
1745 $prototype .= $x;
1746 last;
1747 }
1748 }
1749}
1750
1582 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1583 $prototype =~ s/__attribute__\s*\(\(
1584 (?:
1585 [\w\s]++ # attribute name
1586 (?:\([^)]*+\))? # attribute arguments
1587 \s*+,? # optional comma at the end
1588 )+
1589 \)\)\s+//x;

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

1800 $x = $3;
1801 } else {
1802 $prototype .= $x;
1803 last;
1804 }
1805 }
1806}
1807
1751# xml_escape: replace <, >, and & in the text stream;
1752#
1753# however, formatting controls that are generated internally/locally in the
1754# kernel-doc script are not escaped here; instead, they begin life like
1755# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
1756# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
1757# just before actual output; (this is done by local_unescape())
1758sub xml_escape($) {
1759 my $text = shift;
1760 if ($output_mode eq "man") {
1761 return $text;
1762 }
1763 $text =~ s/\&/\\\\\\amp;/g;
1764 $text =~ s/\</\\\\\\lt;/g;
1765 $text =~ s/\>/\\\\\\gt;/g;
1766 return $text;
1767}
1768
1808
1769# xml_unescape: reverse the effects of xml_escape
1770sub xml_unescape($) {
1771 my $text = shift;
1772 if ($output_mode eq "man") {
1773 return $text;
1774 }
1775 $text =~ s/\\\\\\amp;/\&/g;
1776 $text =~ s/\\\\\\lt;/</g;
1777 $text =~ s/\\\\\\gt;/>/g;
1778 return $text;
1779}
1780
1781# convert local escape strings to html
1782# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
1783sub local_unescape($) {
1784 my $text = shift;
1785 if ($output_mode eq "man") {
1786 return $text;
1787 }
1788 $text =~ s/\\\\\\\\lt:/</g;
1789 $text =~ s/\\\\\\\\gt:/>/g;
1790 return $text;
1791}
1792
1793sub map_filename($) {
1794 my $file;
1795 my ($orig_file) = @_;
1796
1797 if (defined($ENV{'SRCTREE'})) {
1798 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1799 } else {
1800 $file = $orig_file;

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

1821 if (/$export_symbol/) {
1822 $function_table{$2} = 1;
1823 }
1824 }
1825
1826 close(IN);
1827}
1828
1809sub map_filename($) {
1810 my $file;
1811 my ($orig_file) = @_;
1812
1813 if (defined($ENV{'SRCTREE'})) {
1814 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1815 } else {
1816 $file = $orig_file;

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

1837 if (/$export_symbol/) {
1838 $function_table{$2} = 1;
1839 }
1840 }
1841
1842 close(IN);
1843}
1844
1829sub process_file($) {
1830 my $file;
1845#
1846# Parsers for the various processing states.
1847#
1848# STATE_NORMAL: looking for the /** to begin everything.
1849#
1850sub process_normal() {
1851 if (/$doc_start/o) {
1852 $state = STATE_NAME; # next line is always the function name
1853 $in_doc_sect = 0;
1854 $declaration_start_line = $. + 1;
1855 }
1856}
1857
1858#
1859# STATE_NAME: Looking for the "name - description" line
1860#
1861sub process_name($$) {
1862 my $file = shift;
1831 my $identifier;
1863 my $identifier;
1832 my $func;
1833 my $descr;
1864 my $descr;
1834 my $in_purpose = 0;
1835 my $initial_section_counter = $section_counter;
1836 my ($orig_file) = @_;
1837 my $leading_space;
1838
1865
1839 $file = map_filename($orig_file);
1866 if (/$doc_block/o) {
1867 $state = STATE_DOCBLOCK;
1868 $contents = "";
1869 $new_start_line = $. + 1;
1840
1870
1841 if (!open(IN,"<$file")) {
1842 print STDERR "Error: Cannot open file $file\n";
1843 ++$errors;
1844 return;
1871 if ( $1 eq "" ) {
1872 $section = $section_intro;
1873 } else {
1874 $section = $1;
1875 }
1845 }
1876 }
1877 elsif (/$doc_decl/o) {
1878 $identifier = $1;
1879 if (/\s*([\w\s]+?)(\(\))?\s*-/) {
1880 $identifier = $1;
1881 }
1846
1882
1847 $. = 1;
1883 $state = STATE_BODY;
1884 # if there's no @param blocks need to set up default section
1885 # here
1886 $contents = "";
1887 $section = $section_default;
1888 $new_start_line = $. + 1;
1889 if (/-(.*)/) {
1890 # strip leading/trailing/multiple spaces
1891 $descr= $1;
1892 $descr =~ s/^\s*//;
1893 $descr =~ s/\s*$//;
1894 $descr =~ s/\s+/ /g;
1895 $declaration_purpose = $descr;
1896 $state = STATE_BODY_MAYBE;
1897 } else {
1898 $declaration_purpose = "";
1899 }
1848
1900
1849 $section_counter = 0;
1850 while (<IN>) {
1851 while (s/\\\s*$//) {
1852 $_ .= <IN>;
1901 if (($declaration_purpose eq "") && $verbose) {
1902 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
1903 print STDERR $_;
1904 ++$warnings;
1853 }
1905 }
1854 # Replace tabs by spaces
1855 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
1856 if ($state == STATE_NORMAL) {
1857 if (/$doc_start/o) {
1858 $state = STATE_NAME; # next line is always the function name
1859 $in_doc_sect = 0;
1860 $declaration_start_line = $. + 1;
1861 }
1862 } elsif ($state == STATE_NAME) {# this line is the function name (always)
1863 if (/$doc_block/o) {
1864 $state = STATE_DOCBLOCK;
1865 $contents = "";
1866 $new_start_line = $. + 1;
1867
1906
1868 if ( $1 eq "" ) {
1869 $section = $section_intro;
1870 } else {
1871 $section = $1;
1872 }
1873 }
1874 elsif (/$doc_decl/o) {
1875 $identifier = $1;
1876 if (/\s*([\w\s]+?)\s*-/) {
1877 $identifier = $1;
1878 }
1907 if ($identifier =~ m/^struct/) {
1908 $decl_type = 'struct';
1909 } elsif ($identifier =~ m/^union/) {
1910 $decl_type = 'union';
1911 } elsif ($identifier =~ m/^enum/) {
1912 $decl_type = 'enum';
1913 } elsif ($identifier =~ m/^typedef/) {
1914 $decl_type = 'typedef';
1915 } else {
1916 $decl_type = 'function';
1917 }
1879
1918
1880 $state = STATE_FIELD;
1881 # if there's no @param blocks need to set up default section
1882 # here
1883 $contents = "";
1884 $section = $section_default;
1885 $new_start_line = $. + 1;
1886 if (/-(.*)/) {
1887 # strip leading/trailing/multiple spaces
1888 $descr= $1;
1889 $descr =~ s/^\s*//;
1890 $descr =~ s/\s*$//;
1891 $descr =~ s/\s+/ /g;
1892 $declaration_purpose = xml_escape($descr);
1893 $in_purpose = 1;
1894 } else {
1895 $declaration_purpose = "";
1896 }
1919 if ($verbose) {
1920 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
1921 }
1922 } else {
1923 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1924 " - I thought it was a doc line\n";
1925 ++$warnings;
1926 $state = STATE_NORMAL;
1927 }
1928}
1897
1929
1898 if (($declaration_purpose eq "") && $verbose) {
1899 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
1900 print STDERR $_;
1901 ++$warnings;
1902 }
1903
1930
1904 if ($identifier =~ m/^struct/) {
1905 $decl_type = 'struct';
1906 } elsif ($identifier =~ m/^union/) {
1907 $decl_type = 'union';
1908 } elsif ($identifier =~ m/^enum/) {
1909 $decl_type = 'enum';
1910 } elsif ($identifier =~ m/^typedef/) {
1911 $decl_type = 'typedef';
1912 } else {
1913 $decl_type = 'function';
1914 }
1931#
1932# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
1933#
1934sub process_body($$) {
1935 my $file = shift;
1915
1936
1916 if ($verbose) {
1917 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
1918 }
1919 } else {
1920 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1921 " - I thought it was a doc line\n";
1937 if (/$doc_sect/i) { # case insensitive for supported section names
1938 $newsection = $1;
1939 $newcontents = $2;
1940
1941 # map the supported section names to the canonical names
1942 if ($newsection =~ m/^description$/i) {
1943 $newsection = $section_default;
1944 } elsif ($newsection =~ m/^context$/i) {
1945 $newsection = $section_context;
1946 } elsif ($newsection =~ m/^returns?$/i) {
1947 $newsection = $section_return;
1948 } elsif ($newsection =~ m/^\@return$/) {
1949 # special: @return is a section, not a param description
1950 $newsection = $section_return;
1951 }
1952
1953 if (($contents ne "") && ($contents ne "\n")) {
1954 if (!$in_doc_sect && $verbose) {
1955 print STDERR "${file}:$.: warning: contents before sections\n";
1922 ++$warnings;
1956 ++$warnings;
1923 $state = STATE_NORMAL;
1924 }
1957 }
1925 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
1926 if (/$doc_sect/i) { # case insensitive for supported section names
1927 $newsection = $1;
1928 $newcontents = $2;
1958 dump_section($file, $section, $contents);
1959 $section = $section_default;
1960 }
1929
1961
1930 # map the supported section names to the canonical names
1931 if ($newsection =~ m/^description$/i) {
1932 $newsection = $section_default;
1933 } elsif ($newsection =~ m/^context$/i) {
1934 $newsection = $section_context;
1935 } elsif ($newsection =~ m/^returns?$/i) {
1936 $newsection = $section_return;
1937 } elsif ($newsection =~ m/^\@return$/) {
1938 # special: @return is a section, not a param description
1939 $newsection = $section_return;
1940 }
1962 $in_doc_sect = 1;
1963 $state = STATE_BODY;
1964 $contents = $newcontents;
1965 $new_start_line = $.;
1966 while (substr($contents, 0, 1) eq " ") {
1967 $contents = substr($contents, 1);
1968 }
1969 if ($contents ne "") {
1970 $contents .= "\n";
1971 }
1972 $section = $newsection;
1973 $leading_space = undef;
1974 } elsif (/$doc_end/) {
1975 if (($contents ne "") && ($contents ne "\n")) {
1976 dump_section($file, $section, $contents);
1977 $section = $section_default;
1978 $contents = "";
1979 }
1980 # look for doc_com + <text> + doc_end:
1981 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1982 print STDERR "${file}:$.: warning: suspicious ending line: $_";
1983 ++$warnings;
1984 }
1941
1985
1942 if (($contents ne "") && ($contents ne "\n")) {
1943 if (!$in_doc_sect && $verbose) {
1944 print STDERR "${file}:$.: warning: contents before sections\n";
1945 ++$warnings;
1986 $prototype = "";
1987 $state = STATE_PROTO;
1988 $brcount = 0;
1989 } elsif (/$doc_content/) {
1990 # miguel-style comment kludge, look for blank lines after
1991 # @parameter line to signify start of description
1992 if ($1 eq "") {
1993 if ($section =~ m/^@/ || $section eq $section_context) {
1994 dump_section($file, $section, $contents);
1995 $section = $section_default;
1996 $contents = "";
1997 $new_start_line = $.;
1998 } else {
1999 $contents .= "\n";
2000 }
2001 $state = STATE_BODY;
2002 } elsif ($state == STATE_BODY_MAYBE) {
2003 # Continued declaration purpose
2004 chomp($declaration_purpose);
2005 $declaration_purpose .= " " . $1;
2006 $declaration_purpose =~ s/\s+/ /g;
2007 } else {
2008 my $cont = $1;
2009 if ($section =~ m/^@/ || $section eq $section_context) {
2010 if (!defined $leading_space) {
2011 if ($cont =~ m/^(\s+)/) {
2012 $leading_space = $1;
2013 } else {
2014 $leading_space = "";
1946 }
2015 }
1947 dump_section($file, $section, xml_escape($contents));
1948 $section = $section_default;
1949 }
2016 }
2017 $cont =~ s/^$leading_space//;
2018 }
2019 $contents .= $cont . "\n";
2020 }
2021 } else {
2022 # i dont know - bad line? ignore.
2023 print STDERR "${file}:$.: warning: bad line: $_";
2024 ++$warnings;
2025 }
2026}
1950
2027
1951 $in_doc_sect = 1;
1952 $in_purpose = 0;
1953 $contents = $newcontents;
1954 $new_start_line = $.;
1955 while (substr($contents, 0, 1) eq " ") {
1956 $contents = substr($contents, 1);
1957 }
1958 if ($contents ne "") {
1959 $contents .= "\n";
1960 }
1961 $section = $newsection;
1962 $leading_space = undef;
1963 } elsif (/$doc_end/) {
1964 if (($contents ne "") && ($contents ne "\n")) {
1965 dump_section($file, $section, xml_escape($contents));
1966 $section = $section_default;
1967 $contents = "";
1968 }
1969 # look for doc_com + <text> + doc_end:
1970 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1971 print STDERR "${file}:$.: warning: suspicious ending line: $_";
1972 ++$warnings;
1973 }
1974
2028
1975 $prototype = "";
1976 $state = STATE_PROTO;
1977 $brcount = 0;
1978# print STDERR "end of doc comment, looking for prototype\n";
1979 } elsif (/$doc_content/) {
1980 # miguel-style comment kludge, look for blank lines after
1981 # @parameter line to signify start of description
1982 if ($1 eq "") {
1983 if ($section =~ m/^@/ || $section eq $section_context) {
1984 dump_section($file, $section, xml_escape($contents));
1985 $section = $section_default;
1986 $contents = "";
1987 $new_start_line = $.;
1988 } else {
1989 $contents .= "\n";
1990 }
1991 $in_purpose = 0;
1992 } elsif ($in_purpose == 1) {
1993 # Continued declaration purpose
1994 chomp($declaration_purpose);
1995 $declaration_purpose .= " " . xml_escape($1);
1996 $declaration_purpose =~ s/\s+/ /g;
1997 } else {
1998 my $cont = $1;
1999 if ($section =~ m/^@/ || $section eq $section_context) {
2000 if (!defined $leading_space) {
2001 if ($cont =~ m/^(\s+)/) {
2002 $leading_space = $1;
2003 } else {
2004 $leading_space = "";
2005 }
2006 }
2029#
2030# STATE_PROTO: reading a function/whatever prototype.
2031#
2032sub process_proto($$) {
2033 my $file = shift;
2007
2034
2008 $cont =~ s/^$leading_space//;
2009 }
2010 $contents .= $cont . "\n";
2011 }
2012 } else {
2013 # i dont know - bad line? ignore.
2014 print STDERR "${file}:$.: warning: bad line: $_";
2015 ++$warnings;
2035 if (/$doc_inline_oneline/) {
2036 $section = $1;
2037 $contents = $2;
2038 if ($contents ne "") {
2039 $contents .= "\n";
2040 dump_section($file, $section, $contents);
2041 $section = $section_default;
2042 $contents = "";
2043 }
2044 } elsif (/$doc_inline_start/) {
2045 $state = STATE_INLINE;
2046 $inline_doc_state = STATE_INLINE_NAME;
2047 } elsif ($decl_type eq 'function') {
2048 process_proto_function($_, $file);
2049 } else {
2050 process_proto_type($_, $file);
2051 }
2052}
2053
2054#
2055# STATE_DOCBLOCK: within a DOC: block.
2056#
2057sub process_docblock($$) {
2058 my $file = shift;
2059
2060 if (/$doc_end/) {
2061 dump_doc_section($file, $section, $contents);
2062 $section = $section_default;
2063 $contents = "";
2064 $function = "";
2065 %parameterdescs = ();
2066 %parametertypes = ();
2067 @parameterlist = ();
2068 %sections = ();
2069 @sectionlist = ();
2070 $prototype = "";
2071 $state = STATE_NORMAL;
2072 } elsif (/$doc_content/) {
2073 if ( $1 eq "" ) {
2074 $contents .= $blankline;
2075 } else {
2076 $contents .= $1 . "\n";
2077 }
2078 }
2079}
2080
2081#
2082# STATE_INLINE: docbook comments within a prototype.
2083#
2084sub process_inline($$) {
2085 my $file = shift;
2086
2087 # First line (state 1) needs to be a @parameter
2088 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2089 $section = $1;
2090 $contents = $2;
2091 $new_start_line = $.;
2092 if ($contents ne "") {
2093 while (substr($contents, 0, 1) eq " ") {
2094 $contents = substr($contents, 1);
2016 }
2095 }
2017 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2018 # First line (state 1) needs to be a @parameter
2019 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2020 $section = $1;
2021 $contents = $2;
2022 $new_start_line = $.;
2023 if ($contents ne "") {
2024 while (substr($contents, 0, 1) eq " ") {
2025 $contents = substr($contents, 1);
2026 }
2027 $contents .= "\n";
2028 }
2029 $inline_doc_state = STATE_INLINE_TEXT;
2030 # Documentation block end */
2031 } elsif (/$doc_inline_end/) {
2032 if (($contents ne "") && ($contents ne "\n")) {
2033 dump_section($file, $section, xml_escape($contents));
2034 $section = $section_default;
2035 $contents = "";
2036 }
2037 $state = STATE_PROTO;
2038 $inline_doc_state = STATE_INLINE_NA;
2039 # Regular text
2040 } elsif (/$doc_content/) {
2041 if ($inline_doc_state == STATE_INLINE_TEXT) {
2042 $contents .= $1 . "\n";
2043 # nuke leading blank lines
2044 if ($contents =~ /^\s*$/) {
2045 $contents = "";
2046 }
2047 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2048 $inline_doc_state = STATE_INLINE_ERROR;
2049 print STDERR "${file}:$.: warning: ";
2050 print STDERR "Incorrect use of kernel-doc format: $_";
2051 ++$warnings;
2052 }
2096 $contents .= "\n";
2097 }
2098 $inline_doc_state = STATE_INLINE_TEXT;
2099 # Documentation block end */
2100 } elsif (/$doc_inline_end/) {
2101 if (($contents ne "") && ($contents ne "\n")) {
2102 dump_section($file, $section, $contents);
2103 $section = $section_default;
2104 $contents = "";
2105 }
2106 $state = STATE_PROTO;
2107 $inline_doc_state = STATE_INLINE_NA;
2108 # Regular text
2109 } elsif (/$doc_content/) {
2110 if ($inline_doc_state == STATE_INLINE_TEXT) {
2111 $contents .= $1 . "\n";
2112 # nuke leading blank lines
2113 if ($contents =~ /^\s*$/) {
2114 $contents = "";
2053 }
2115 }
2054 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2055 if (/$doc_inline_oneline/) {
2056 $section = $1;
2057 $contents = $2;
2058 if ($contents ne "") {
2059 $contents .= "\n";
2060 dump_section($file, $section, xml_escape($contents));
2061 $section = $section_default;
2062 $contents = "";
2063 }
2064 } elsif (/$doc_inline_start/) {
2065 $state = STATE_INLINE;
2066 $inline_doc_state = STATE_INLINE_NAME;
2067 } elsif ($decl_type eq 'function') {
2068 process_proto_function($_, $file);
2069 } else {
2070 process_proto_type($_, $file);
2071 }
2116 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2117 $inline_doc_state = STATE_INLINE_ERROR;
2118 print STDERR "${file}:$.: warning: ";
2119 print STDERR "Incorrect use of kernel-doc format: $_";
2120 ++$warnings;
2121 }
2122 }
2123}
2124
2125
2126sub process_file($) {
2127 my $file;
2128 my $initial_section_counter = $section_counter;
2129 my ($orig_file) = @_;
2130
2131 $file = map_filename($orig_file);
2132
2133 if (!open(IN,"<$file")) {
2134 print STDERR "Error: Cannot open file $file\n";
2135 ++$errors;
2136 return;
2137 }
2138
2139 $. = 1;
2140
2141 $section_counter = 0;
2142 while (<IN>) {
2143 while (s/\\\s*$//) {
2144 $_ .= <IN>;
2145 }
2146 # Replace tabs by spaces
2147 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2148 # Hand this line to the appropriate state handler
2149 if ($state == STATE_NORMAL) {
2150 process_normal();
2151 } elsif ($state == STATE_NAME) {
2152 process_name($file, $_);
2153 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
2154 process_body($file, $_);
2155 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2156 process_inline($file, $_);
2157 } elsif ($state == STATE_PROTO) {
2158 process_proto($file, $_);
2072 } elsif ($state == STATE_DOCBLOCK) {
2159 } elsif ($state == STATE_DOCBLOCK) {
2073 if (/$doc_end/)
2074 {
2075 dump_doc_section($file, $section, xml_escape($contents));
2076 $section = $section_default;
2077 $contents = "";
2078 $function = "";
2079 %parameterdescs = ();
2080 %parametertypes = ();
2081 @parameterlist = ();
2082 %sections = ();
2083 @sectionlist = ();
2084 $prototype = "";
2085 $state = STATE_NORMAL;
2086 }
2087 elsif (/$doc_content/)
2088 {
2089 if ( $1 eq "" )
2090 {
2091 $contents .= $blankline;
2092 }
2093 else
2094 {
2095 $contents .= $1 . "\n";
2096 }
2097 }
2160 process_docblock($file, $_);
2098 }
2099 }
2161 }
2162 }
2163
2164 # Make sure we got something interesting.
2100 if ($initial_section_counter == $section_counter) {
2101 if ($output_mode ne "none") {
2102 print STDERR "${file}:1: warning: no structured comments found\n";
2103 }
2104 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2105 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2106 }
2107 }

--- 50 unchanged lines hidden --- 		2165 if ($initial_section_counter == $section_counter) {
2166 if ($output_mode ne "none") {
2167 print STDERR "${file}:1: warning: no structured comments found\n";
2168 }
2169 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2170 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2171 }
2172 }

--- 50 unchanged lines hidden ---