kernel-doc (3cac2bc41d1b4c51a1f31059bf65f4dc7cfb35f5) kernel-doc (d742f24d6cce67656d93a704563c1594877a4ea0)
1#!/usr/bin/env perl
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 ##

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

331 STATE_BODY_MAYBE => 2, # body - or maybe more description
332 STATE_BODY => 3, # the body of the comment
333 STATE_PROTO => 4, # scanning prototype
334 STATE_DOCBLOCK => 5, # documentation block
335 STATE_INLINE => 6, # gathering documentation outside main block
336};
337my $state;
338my $in_doc_sect;
1#!/usr/bin/env perl
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 ##

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

331 STATE_BODY_MAYBE => 2, # body - or maybe more description
332 STATE_BODY => 3, # the body of the comment
333 STATE_PROTO => 4, # scanning prototype
334 STATE_DOCBLOCK => 5, # documentation block
335 STATE_INLINE => 6, # gathering documentation outside main block
336};
337my $state;
338my $in_doc_sect;
339my $leading_space;
339
340# Inline documentation state
341use constant {
342 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
343 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
344 STATE_INLINE_TEXT => 2, # looking for member documentation
345 STATE_INLINE_END => 3, # done
346 STATE_INLINE_ERROR => 4, # error - Comment without header was found.

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

1860 } else {
1861 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1862 " - I thought it was a doc line\n";
1863 ++$warnings;
1864 $state = STATE_NORMAL;
1865 }
1866}
1867
340
341# Inline documentation state
342use constant {
343 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
344 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
345 STATE_INLINE_TEXT => 2, # looking for member documentation
346 STATE_INLINE_END => 3, # done
347 STATE_INLINE_ERROR => 4, # error - Comment without header was found.

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

1861 } else {
1862 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1863 " - I thought it was a doc line\n";
1864 ++$warnings;
1865 $state = STATE_NORMAL;
1866 }
1867}
1868
1869
1870#
1871# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
1872#
1873sub process_body($$) {
1874 my $file = shift;
1875
1876 if (/$doc_sect/i) { # case insensitive for supported section names
1877 $newsection = $1;
1878 $newcontents = $2;
1879
1880 # map the supported section names to the canonical names
1881 if ($newsection =~ m/^description$/i) {
1882 $newsection = $section_default;
1883 } elsif ($newsection =~ m/^context$/i) {
1884 $newsection = $section_context;
1885 } elsif ($newsection =~ m/^returns?$/i) {
1886 $newsection = $section_return;
1887 } elsif ($newsection =~ m/^\@return$/) {
1888 # special: @return is a section, not a param description
1889 $newsection = $section_return;
1890 }
1891
1892 if (($contents ne "") && ($contents ne "\n")) {
1893 if (!$in_doc_sect && $verbose) {
1894 print STDERR "${file}:$.: warning: contents before sections\n";
1895 ++$warnings;
1896 }
1897 dump_section($file, $section, $contents);
1898 $section = $section_default;
1899 }
1900
1901 $in_doc_sect = 1;
1902 $state = STATE_BODY;
1903 $contents = $newcontents;
1904 $new_start_line = $.;
1905 while (substr($contents, 0, 1) eq " ") {
1906 $contents = substr($contents, 1);
1907 }
1908 if ($contents ne "") {
1909 $contents .= "\n";
1910 }
1911 $section = $newsection;
1912 $leading_space = undef;
1913 } elsif (/$doc_end/) {
1914 if (($contents ne "") && ($contents ne "\n")) {
1915 dump_section($file, $section, $contents);
1916 $section = $section_default;
1917 $contents = "";
1918 }
1919 # look for doc_com + <text> + doc_end:
1920 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1921 print STDERR "${file}:$.: warning: suspicious ending line: $_";
1922 ++$warnings;
1923 }
1924
1925 $prototype = "";
1926 $state = STATE_PROTO;
1927 $brcount = 0;
1928 } elsif (/$doc_content/) {
1929 # miguel-style comment kludge, look for blank lines after
1930 # @parameter line to signify start of description
1931 if ($1 eq "") {
1932 if ($section =~ m/^@/ || $section eq $section_context) {
1933 dump_section($file, $section, $contents);
1934 $section = $section_default;
1935 $contents = "";
1936 $new_start_line = $.;
1937 } else {
1938 $contents .= "\n";
1939 }
1940 $state = STATE_BODY;
1941 } elsif ($state == STATE_BODY_MAYBE) {
1942 # Continued declaration purpose
1943 chomp($declaration_purpose);
1944 $declaration_purpose .= " " . $1;
1945 $declaration_purpose =~ s/\s+/ /g;
1946 } else {
1947 my $cont = $1;
1948 if ($section =~ m/^@/ || $section eq $section_context) {
1949 if (!defined $leading_space) {
1950 if ($cont =~ m/^(\s+)/) {
1951 $leading_space = $1;
1952 } else {
1953 $leading_space = "";
1954 }
1955 }
1956 $cont =~ s/^$leading_space//;
1957 }
1958 $contents .= $cont . "\n";
1959 }
1960 } else {
1961 # i dont know - bad line? ignore.
1962 print STDERR "${file}:$.: warning: bad line: $_";
1963 ++$warnings;
1964 }
1965}
1966
1967
1868sub process_file($) {
1869 my $file;
1870 my $func;
1871 my $initial_section_counter = $section_counter;
1872 my ($orig_file) = @_;
1968sub process_file($) {
1969 my $file;
1970 my $func;
1971 my $initial_section_counter = $section_counter;
1972 my ($orig_file) = @_;
1873 my $leading_space;
1874
1875 $file = map_filename($orig_file);
1876
1877 if (!open(IN,"<$file")) {
1878 print STDERR "Error: Cannot open file $file\n";
1879 ++$errors;
1880 return;
1881 }

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

1889 }
1890 # Replace tabs by spaces
1891 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
1892 if ($state == STATE_NORMAL) {
1893 process_normal();
1894 } elsif ($state == STATE_NAME) {
1895 process_name($file, $_);
1896 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
1973
1974 $file = map_filename($orig_file);
1975
1976 if (!open(IN,"<$file")) {
1977 print STDERR "Error: Cannot open file $file\n";
1978 ++$errors;
1979 return;
1980 }

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

1988 }
1989 # Replace tabs by spaces
1990 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
1991 if ($state == STATE_NORMAL) {
1992 process_normal();
1993 } elsif ($state == STATE_NAME) {
1994 process_name($file, $_);
1995 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
1897 if (/$doc_sect/i) { # case insensitive for supported section names
1898 $newsection = $1;
1899 $newcontents = $2;
1900
1901 # map the supported section names to the canonical names
1902 if ($newsection =~ m/^description$/i) {
1903 $newsection = $section_default;
1904 } elsif ($newsection =~ m/^context$/i) {
1905 $newsection = $section_context;
1906 } elsif ($newsection =~ m/^returns?$/i) {
1907 $newsection = $section_return;
1908 } elsif ($newsection =~ m/^\@return$/) {
1909 # special: @return is a section, not a param description
1910 $newsection = $section_return;
1911 }
1912
1913 if (($contents ne "") && ($contents ne "\n")) {
1914 if (!$in_doc_sect && $verbose) {
1915 print STDERR "${file}:$.: warning: contents before sections\n";
1916 ++$warnings;
1917 }
1918 dump_section($file, $section, $contents);
1919 $section = $section_default;
1920 }
1921
1922 $in_doc_sect = 1;
1923 $state = STATE_BODY;
1924 $contents = $newcontents;
1925 $new_start_line = $.;
1926 while (substr($contents, 0, 1) eq " ") {
1927 $contents = substr($contents, 1);
1928 }
1929 if ($contents ne "") {
1930 $contents .= "\n";
1931 }
1932 $section = $newsection;
1933 $leading_space = undef;
1934 } elsif (/$doc_end/) {
1935 if (($contents ne "") && ($contents ne "\n")) {
1936 dump_section($file, $section, $contents);
1937 $section = $section_default;
1938 $contents = "";
1939 }
1940 # look for doc_com + <text> + doc_end:
1941 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1942 print STDERR "${file}:$.: warning: suspicious ending line: $_";
1943 ++$warnings;
1944 }
1945
1946 $prototype = "";
1947 $state = STATE_PROTO;
1948 $brcount = 0;
1949# print STDERR "end of doc comment, looking for prototype\n";
1950 } elsif (/$doc_content/) {
1951 # miguel-style comment kludge, look for blank lines after
1952 # @parameter line to signify start of description
1953 if ($1 eq "") {
1954 if ($section =~ m/^@/ || $section eq $section_context) {
1955 dump_section($file, $section, $contents);
1956 $section = $section_default;
1957 $contents = "";
1958 $new_start_line = $.;
1959 } else {
1960 $contents .= "\n";
1961 }
1962 $state = STATE_BODY;
1963 } elsif ($state == STATE_BODY_MAYBE) {
1964 # Continued declaration purpose
1965 chomp($declaration_purpose);
1966 $declaration_purpose .= " " . $1;
1967 $declaration_purpose =~ s/\s+/ /g;
1968 } else {
1969 my $cont = $1;
1970 if ($section =~ m/^@/ || $section eq $section_context) {
1971 if (!defined $leading_space) {
1972 if ($cont =~ m/^(\s+)/) {
1973 $leading_space = $1;
1974 } else {
1975 $leading_space = "";
1976 }
1977 }
1978
1979 $cont =~ s/^$leading_space//;
1980 }
1981 $contents .= $cont . "\n";
1982 }
1983 } else {
1984 # i dont know - bad line? ignore.
1985 print STDERR "${file}:$.: warning: bad line: $_";
1986 ++$warnings;
1987 }
1996 process_body($file, $_);
1988 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
1989 # First line (state 1) needs to be a @parameter
1990 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
1991 $section = $1;
1992 $contents = $2;
1993 $new_start_line = $.;
1994 if ($contents ne "") {
1995 while (substr($contents, 0, 1) eq " ") {

--- 133 unchanged lines hidden --- 		1997 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
1998 # First line (state 1) needs to be a @parameter
1999 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2000 $section = $1;
2001 $contents = $2;
2002 $new_start_line = $.;
2003 if ($contents ne "") {
2004 while (substr($contents, 0, 1) eq " ") {

--- 133 unchanged lines hidden ---