kernel-doc (e2701603f72cd38e99c6b1da13c8e99bc27b2f34) kernel-doc (d40e1e6532efbb40f8fc1f5af093063a3d186754)
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 ##

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

464 } elsif ($name eq "@\.\.\.") {
465# print STDERR "parameter def '...' = '$contents'\n";
466 $name = "...";
467 $parameterdescs{$name} = $contents;
468 $sectcheck = $sectcheck . $name . " ";
469 } else {
470# print STDERR "other section '$name' = '$contents'\n";
471 if (defined($sections{$name}) && ($sections{$name} ne "")) {
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 ##

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

464 } elsif ($name eq "@\.\.\.") {
465# print STDERR "parameter def '...' = '$contents'\n";
466 $name = "...";
467 $parameterdescs{$name} = $contents;
468 $sectcheck = $sectcheck . $name . " ";
469 } else {
470# print STDERR "other section '$name' = '$contents'\n";
471 if (defined($sections{$name}) && ($sections{$name} ne "")) {
472 print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
472 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
473 ++$errors;
474 }
475 $sections{$name} = $contents;
476 push @sectionlist, $name;
477 }
478}
479
480##

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

1815 'parametertypes' => \%parametertypes,
1816 'sectionlist' => \@sectionlist,
1817 'sections' => \%sections,
1818 'purpose' => $declaration_purpose,
1819 'type' => $decl_type
1820 });
1821 }
1822 else {
473 ++$errors;
474 }
475 $sections{$name} = $contents;
476 push @sectionlist, $name;
477 }
478}
479
480##

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

1815 'parametertypes' => \%parametertypes,
1816 'sectionlist' => \@sectionlist,
1817 'sections' => \%sections,
1818 'purpose' => $declaration_purpose,
1819 'type' => $decl_type
1820 });
1821 }
1822 else {
1823 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1823 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1824 ++$errors;
1825 }
1826}
1827
1828sub dump_enum($$) {
1829 my $x = shift;
1830 my $file = shift;
1831

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

1836 $declaration_name = $1;
1837 my $members = $2;
1838
1839 foreach my $arg (split ',', $members) {
1840 $arg =~ s/^\s*(\w+).*/$1/;
1841 push @parameterlist, $arg;
1842 if (!$parameterdescs{$arg}) {
1843 $parameterdescs{$arg} = $undescribed;
1824 ++$errors;
1825 }
1826}
1827
1828sub dump_enum($$) {
1829 my $x = shift;
1830 my $file = shift;
1831

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

1836 $declaration_name = $1;
1837 my $members = $2;
1838
1839 foreach my $arg (split ',', $members) {
1840 $arg =~ s/^\s*(\w+).*/$1/;
1841 push @parameterlist, $arg;
1842 if (!$parameterdescs{$arg}) {
1843 $parameterdescs{$arg} = $undescribed;
1844 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1844 print STDERR "${file}:$.: warning: Enum value '$arg' ".
1845 "not described in enum '$declaration_name'\n";
1846 }
1847
1848 }
1849
1850 output_declaration($declaration_name,
1851 'enum',
1852 {'enum' => $declaration_name,
1853 'module' => $modulename,
1854 'parameterlist' => \@parameterlist,
1855 'parameterdescs' => \%parameterdescs,
1856 'sectionlist' => \@sectionlist,
1857 'sections' => \%sections,
1858 'purpose' => $declaration_purpose
1859 });
1860 }
1861 else {
1845 "not described in enum '$declaration_name'\n";
1846 }
1847
1848 }
1849
1850 output_declaration($declaration_name,
1851 'enum',
1852 {'enum' => $declaration_name,
1853 'module' => $modulename,
1854 'parameterlist' => \@parameterlist,
1855 'parameterdescs' => \%parameterdescs,
1856 'sectionlist' => \@sectionlist,
1857 'sections' => \%sections,
1858 'purpose' => $declaration_purpose
1859 });
1860 }
1861 else {
1862 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1862 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1863 ++$errors;
1864 }
1865}
1866
1867sub dump_typedef($$) {
1868 my $x = shift;
1869 my $file = shift;
1870

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

1882 {'typedef' => $declaration_name,
1883 'module' => $modulename,
1884 'sectionlist' => \@sectionlist,
1885 'sections' => \%sections,
1886 'purpose' => $declaration_purpose
1887 });
1888 }
1889 else {
1863 ++$errors;
1864 }
1865}
1866
1867sub dump_typedef($$) {
1868 my $x = shift;
1869 my $file = shift;
1870

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

1882 {'typedef' => $declaration_name,
1883 'module' => $modulename,
1884 'sectionlist' => \@sectionlist,
1885 'sections' => \%sections,
1886 'purpose' => $declaration_purpose
1887 });
1888 }
1889 else {
1890 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1890 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
1891 ++$errors;
1892 }
1893}
1894
1895sub save_struct_actual($) {
1896 my $actual = shift;
1897
1898 # strip all spaces from the actual param so that it looks like one string item

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

2014 # but inline preprocessor statements);
2015 # also ignore unnamed structs/unions;
2016 if (!$anon_struct_union) {
2017 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2018
2019 $parameterdescs{$param_name} = $undescribed;
2020
2021 if (($type eq 'function') || ($type eq 'enum')) {
1891 ++$errors;
1892 }
1893}
1894
1895sub save_struct_actual($) {
1896 my $actual = shift;
1897
1898 # strip all spaces from the actual param so that it looks like one string item

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

2014 # but inline preprocessor statements);
2015 # also ignore unnamed structs/unions;
2016 if (!$anon_struct_union) {
2017 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2018
2019 $parameterdescs{$param_name} = $undescribed;
2020
2021 if (($type eq 'function') || ($type eq 'enum')) {
2022 print STDERR "Warning(${file}:$.): Function parameter ".
2022 print STDERR "${file}:$.: warning: Function parameter ".
2023 "or member '$param' not " .
2024 "described in '$declaration_name'\n";
2025 }
2023 "or member '$param' not " .
2024 "described in '$declaration_name'\n";
2025 }
2026 print STDERR "Warning(${file}:$.):" .
2026 print STDERR "${file}:$.: warning:" .
2027 " No description found for parameter '$param'\n";
2028 ++$warnings;
2029 }
2030 }
2031
2032 $param = xml_escape($param);
2033
2034 # strip spaces from $param so that it is one continuous string

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

2069 ##$prm_clean =~ s/^\**//;
2070 if ($prm_clean eq $sects[$sx]) {
2071 $err = 0;
2072 last;
2073 }
2074 }
2075 if ($err) {
2076 if ($decl_type eq "function") {
2027 " No description found for parameter '$param'\n";
2028 ++$warnings;
2029 }
2030 }
2031
2032 $param = xml_escape($param);
2033
2034 # strip spaces from $param so that it is one continuous string

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

2069 ##$prm_clean =~ s/^\**//;
2070 if ($prm_clean eq $sects[$sx]) {
2071 $err = 0;
2072 last;
2073 }
2074 }
2075 if ($err) {
2076 if ($decl_type eq "function") {
2077 print STDERR "Warning(${file}:$.): " .
2077 print STDERR "${file}:$.: warning: " .
2078 "Excess function parameter " .
2079 "'$sects[$sx]' " .
2080 "description in '$decl_name'\n";
2081 ++$warnings;
2082 } else {
2083 if ($nested !~ m/\Q$sects[$sx]\E/) {
2078 "Excess function parameter " .
2079 "'$sects[$sx]' " .
2080 "description in '$decl_name'\n";
2081 ++$warnings;
2082 } else {
2083 if ($nested !~ m/\Q$sects[$sx]\E/) {
2084 print STDERR "Warning(${file}:$.): " .
2084 print STDERR "${file}:$.: warning: " .
2085 "Excess struct/union/enum/typedef member " .
2086 "'$sects[$sx]' " .
2087 "description in '$decl_name'\n";
2088 ++$warnings;
2089 }
2090 }
2091 }
2092 }

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

2102 # Ignore an empty return type (It's a macro)
2103 # Ignore functions with a "void" return type. (But don't ignore "void *")
2104 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2105 return;
2106 }
2107
2108 if (!defined($sections{$section_return}) ||
2109 $sections{$section_return} eq "") {
2085 "Excess struct/union/enum/typedef member " .
2086 "'$sects[$sx]' " .
2087 "description in '$decl_name'\n";
2088 ++$warnings;
2089 }
2090 }
2091 }
2092 }

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

2102 # Ignore an empty return type (It's a macro)
2103 # Ignore functions with a "void" return type. (But don't ignore "void *")
2104 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2105 return;
2106 }
2107
2108 if (!defined($sections{$section_return}) ||
2109 $sections{$section_return} eq "") {
2110 print STDERR "Warning(${file}:$.): " .
2110 print STDERR "${file}:$.: warning: " .
2111 "No description found for return value of " .
2112 "'$declaration_name'\n";
2113 ++$warnings;
2114 }
2115}
2116
2117##
2118# takes a function prototype and the name of the current file being

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

2181 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2182 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
2183 $return_type = $1;
2184 $declaration_name = $2;
2185 my $args = $3;
2186
2187 create_parameterlist($args, ',', $file);
2188 } else {
2111 "No description found for return value of " .
2112 "'$declaration_name'\n";
2113 ++$warnings;
2114 }
2115}
2116
2117##
2118# takes a function prototype and the name of the current file being

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

2181 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2182 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
2183 $return_type = $1;
2184 $declaration_name = $2;
2185 my $args = $3;
2186
2187 create_parameterlist($args, ',', $file);
2188 } else {
2189 print STDERR "Warning(${file}:$.): cannot understand function prototype: '$prototype'\n";
2189 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2190 return;
2191 }
2192
2193 my $prms = join " ", @parameterlist;
2194 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2195
2196 # This check emits a lot of warnings at the moment, because many
2197 # functions don't have a 'Return' doc section. So until the number

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

2246 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2247 $tracepointname = $2;
2248 }
2249 $tracepointname =~ s/^\s+//; #strip leading whitespace
2250 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2251 $tracepointargs = $1;
2252 }
2253 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2190 return;
2191 }
2192
2193 my $prms = join " ", @parameterlist;
2194 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2195
2196 # This check emits a lot of warnings at the moment, because many
2197 # functions don't have a 'Return' doc section. So until the number

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

2246 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2247 $tracepointname = $2;
2248 }
2249 $tracepointname =~ s/^\s+//; #strip leading whitespace
2250 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2251 $tracepointargs = $1;
2252 }
2253 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2254 print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
2254 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2255 "$prototype\n";
2256 } else {
2257 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2258 }
2259}
2260
2261sub syscall_munge() {
2262 my $void = 0;

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

2445 $descr =~ s/\s+/ /g;
2446 $declaration_purpose = xml_escape($descr);
2447 $in_purpose = 1;
2448 } else {
2449 $declaration_purpose = "";
2450 }
2451
2452 if (($declaration_purpose eq "") && $verbose) {
2255 "$prototype\n";
2256 } else {
2257 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2258 }
2259}
2260
2261sub syscall_munge() {
2262 my $void = 0;

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

2445 $descr =~ s/\s+/ /g;
2446 $declaration_purpose = xml_escape($descr);
2447 $in_purpose = 1;
2448 } else {
2449 $declaration_purpose = "";
2450 }
2451
2452 if (($declaration_purpose eq "") && $verbose) {
2453 print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
2453 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2454 print STDERR $_;
2455 ++$warnings;
2456 }
2457
2458 if ($identifier =~ m/^struct/) {
2459 $decl_type = 'struct';
2460 } elsif ($identifier =~ m/^union/) {
2461 $decl_type = 'union';
2462 } elsif ($identifier =~ m/^enum/) {
2463 $decl_type = 'enum';
2464 } elsif ($identifier =~ m/^typedef/) {
2465 $decl_type = 'typedef';
2466 } else {
2467 $decl_type = 'function';
2468 }
2469
2470 if ($verbose) {
2454 print STDERR $_;
2455 ++$warnings;
2456 }
2457
2458 if ($identifier =~ m/^struct/) {
2459 $decl_type = 'struct';
2460 } elsif ($identifier =~ m/^union/) {
2461 $decl_type = 'union';
2462 } elsif ($identifier =~ m/^enum/) {
2463 $decl_type = 'enum';
2464 } elsif ($identifier =~ m/^typedef/) {
2465 $decl_type = 'typedef';
2466 } else {
2467 $decl_type = 'function';
2468 }
2469
2470 if ($verbose) {
2471 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
2471 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2472 }
2473 } else {
2472 }
2473 } else {
2474 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
2474 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2475 " - I thought it was a doc line\n";
2476 ++$warnings;
2477 $state = 0;
2478 }
2479 } elsif ($state == 2) { # look for head: lines, and include content
2480 if (/$doc_sect/o) {
2481 $newsection = $1;
2482 $newcontents = $2;
2483
2484 if (($contents ne "") && ($contents ne "\n")) {
2485 if (!$in_doc_sect && $verbose) {
2475 " - I thought it was a doc line\n";
2476 ++$warnings;
2477 $state = 0;
2478 }
2479 } elsif ($state == 2) { # look for head: lines, and include content
2480 if (/$doc_sect/o) {
2481 $newsection = $1;
2482 $newcontents = $2;
2483
2484 if (($contents ne "") && ($contents ne "\n")) {
2485 if (!$in_doc_sect && $verbose) {
2486 print STDERR "Warning(${file}:$.): contents before sections\n";
2486 print STDERR "${file}:$.: warning: contents before sections\n";
2487 ++$warnings;
2488 }
2489 dump_section($file, $section, xml_escape($contents));
2490 $section = $section_default;
2491 }
2492
2493 $in_doc_sect = 1;
2494 $in_purpose = 0;

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

2504 } elsif (/$doc_end/) {
2505 if (($contents ne "") && ($contents ne "\n")) {
2506 dump_section($file, $section, xml_escape($contents));
2507 $section = $section_default;
2508 $contents = "";
2509 }
2510 # look for doc_com + <text> + doc_end:
2511 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2487 ++$warnings;
2488 }
2489 dump_section($file, $section, xml_escape($contents));
2490 $section = $section_default;
2491 }
2492
2493 $in_doc_sect = 1;
2494 $in_purpose = 0;

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

2504 } elsif (/$doc_end/) {
2505 if (($contents ne "") && ($contents ne "\n")) {
2506 dump_section($file, $section, xml_escape($contents));
2507 $section = $section_default;
2508 $contents = "";
2509 }
2510 # look for doc_com + <text> + doc_end:
2511 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2512 print STDERR "Warning(${file}:$.): suspicious ending line: $_";
2512 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2513 ++$warnings;
2514 }
2515
2516 $prototype = "";
2517 $state = 3;
2518 $brcount = 0;
2519# print STDERR "end of doc comment, looking for prototype\n";
2520 } elsif (/$doc_content/) {

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

2534 chomp($declaration_purpose);
2535 $declaration_purpose .= " " . xml_escape($1);
2536 $declaration_purpose =~ s/\s+/ /g;
2537 } else {
2538 $contents .= $1 . "\n";
2539 }
2540 } else {
2541 # i dont know - bad line? ignore.
2513 ++$warnings;
2514 }
2515
2516 $prototype = "";
2517 $state = 3;
2518 $brcount = 0;
2519# print STDERR "end of doc comment, looking for prototype\n";
2520 } elsif (/$doc_content/) {

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

2534 chomp($declaration_purpose);
2535 $declaration_purpose .= " " . xml_escape($1);
2536 $declaration_purpose =~ s/\s+/ /g;
2537 } else {
2538 $contents .= $1 . "\n";
2539 }
2540 } else {
2541 # i dont know - bad line? ignore.
2542 print STDERR "Warning(${file}:$.): bad line: $_";
2542 print STDERR "${file}:$.: warning: bad line: $_";
2543 ++$warnings;
2544 }
2545 } elsif ($state == 5) { # scanning for split parameters
2546 # First line (state 1) needs to be a @parameter
2547 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2548 $section = $1;
2549 $contents = $2;
2550 if ($contents ne "") {

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

2626 else
2627 {
2628 $contents .= $1 . "\n";
2629 }
2630 }
2631 }
2632 }
2633 if ($initial_section_counter == $section_counter) {
2543 ++$warnings;
2544 }
2545 } elsif ($state == 5) { # scanning for split parameters
2546 # First line (state 1) needs to be a @parameter
2547 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2548 $section = $1;
2549 $contents = $2;
2550 if ($contents ne "") {

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

2626 else
2627 {
2628 $contents .= $1 . "\n";
2629 }
2630 }
2631 }
2632 }
2633 if ($initial_section_counter == $section_counter) {
2634 print STDERR "Warning(${file}): no structured comments found\n";
2634 print STDERR "${file}:1: warning: no structured comments found\n";
2635 if (($function_only == 1) && ($show_not_found == 1)) {
2636 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2637 }
2638 if ($output_mode eq "xml") {
2639 # The template wants at least one RefEntry here; make one.
2640 print "<refentry>\n";
2641 print " <refnamediv>\n";
2642 print " <refname>\n";

--- 61 unchanged lines hidden --- 		2635 if (($function_only == 1) && ($show_not_found == 1)) {
2636 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2637 }
2638 if ($output_mode eq "xml") {
2639 # The template wants at least one RefEntry here; make one.
2640 print "<refentry>\n";
2641 print " <refnamediv>\n";
2642 print " <refname>\n";

--- 61 unchanged lines hidden ---