kernel-doc (715a1284d89a740b197b3bad5eb20d36a397382f) kernel-doc (52042e2db45290f6a512d525518488b7bf143531)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
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> ##

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

377 # proper kernel-doc and ignore the rest.
378};
379my $inline_doc_state;
380
381#declaration types: can be
382# 'function', 'struct', 'union', 'enum', 'typedef'
383my $decl_type;
384
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
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> ##

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

377 # proper kernel-doc and ignore the rest.
378};
379my $inline_doc_state;
380
381#declaration types: can be
382# 'function', 'struct', 'union', 'enum', 'typedef'
383my $decl_type;
384
385# Name of the kernel-doc identifier for non-DOC markups
386my $identifier;
387
385my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
386my $doc_end = '\*/';
387my $doc_com = '\s*\*\s*';
388my $doc_com_body = '\s*\* ?';
389my $doc_decl = $doc_com . '(\w+)';
390# @params and a strictly limited set of supported section names
391my $doc_sect = $doc_com .
392 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';

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

1198 my $x = shift;
1199 my $file = shift;
1200
1201 if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
1202 my $decl_type = $1;
1203 $declaration_name = $2;
1204 my $members = $3;
1205
388my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
389my $doc_end = '\*/';
390my $doc_com = '\s*\*\s*';
391my $doc_com_body = '\s*\* ?';
392my $doc_decl = $doc_com . '(\w+)';
393# @params and a strictly limited set of supported section names
394my $doc_sect = $doc_com .
395 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';

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

1201 my $x = shift;
1202 my $file = shift;
1203
1204 if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
1205 my $decl_type = $1;
1206 $declaration_name = $2;
1207 my $members = $3;
1208
1209 if ($identifier ne $declaration_name) {
1210 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
1211 return;
1212 }
1213
1206 # ignore members marked private:
1207 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1208 $members =~ s/\/\*\s*private:.*//gosi;
1209 # strip comments:
1210 $members =~ s/\/\*.*?\*\///gos;
1211 # strip attributes
1212 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1213 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;

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

1386 $declaration_name = $2;
1387 $members = $1;
1388 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1389 $declaration_name = $1;
1390 $members = $2;
1391 }
1392
1393 if ($members) {
1214 # ignore members marked private:
1215 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1216 $members =~ s/\/\*\s*private:.*//gosi;
1217 # strip comments:
1218 $members =~ s/\/\*.*?\*\///gos;
1219 # strip attributes
1220 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1221 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;

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

1394 $declaration_name = $2;
1395 $members = $1;
1396 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1397 $declaration_name = $1;
1398 $members = $2;
1399 }
1400
1401 if ($members) {
1402 if ($identifier ne $declaration_name) {
1403 print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1404 return;
1405 }
1406
1394 my %_members;
1395
1396 $members =~ s/\s+$//;
1397
1398 foreach my $arg (split ',', $members) {
1399 $arg =~ s/^\s*(\w+).*/$1/;
1400 push @parameterlist, $arg;
1401 if (!$parameterdescs{$arg}) {

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

1446
1447 # Parse function typedef prototypes
1448 if ($x =~ $typedef1 || $x =~ $typedef2) {
1449 $return_type = $1;
1450 $declaration_name = $2;
1451 my $args = $3;
1452 $return_type =~ s/^\s+//;
1453
1407 my %_members;
1408
1409 $members =~ s/\s+$//;
1410
1411 foreach my $arg (split ',', $members) {
1412 $arg =~ s/^\s*(\w+).*/$1/;
1413 push @parameterlist, $arg;
1414 if (!$parameterdescs{$arg}) {

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

1459
1460 # Parse function typedef prototypes
1461 if ($x =~ $typedef1 || $x =~ $typedef2) {
1462 $return_type = $1;
1463 $declaration_name = $2;
1464 my $args = $3;
1465 $return_type =~ s/^\s+//;
1466
1467 if ($identifier ne $declaration_name) {
1468 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1469 return;
1470 }
1471
1454 create_parameterlist($args, ',', $file, $declaration_name);
1455
1456 output_declaration($declaration_name,
1457 'function',
1458 {'function' => $declaration_name,
1459 'typedef' => 1,
1460 'module' => $modulename,
1461 'functiontype' => $return_type,

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

1472 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1473 $x =~ s/\(*.\)\s*;$/;/;
1474 $x =~ s/\[*.\]\s*;$/;/;
1475 }
1476
1477 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1478 $declaration_name = $1;
1479
1472 create_parameterlist($args, ',', $file, $declaration_name);
1473
1474 output_declaration($declaration_name,
1475 'function',
1476 {'function' => $declaration_name,
1477 'typedef' => 1,
1478 'module' => $modulename,
1479 'functiontype' => $return_type,

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

1490 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1491 $x =~ s/\(*.\)\s*;$/;/;
1492 $x =~ s/\[*.\]\s*;$/;/;
1493 }
1494
1495 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1496 $declaration_name = $1;
1497
1498 if ($identifier ne $declaration_name) {
1499 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
1500 return;
1501 }
1502
1480 output_declaration($declaration_name,
1481 'typedef',
1482 {'typedef' => $declaration_name,
1483 'module' => $modulename,
1484 'sectionlist' => \@sectionlist,
1485 'sections' => \%sections,
1486 'purpose' => $declaration_purpose
1487 });

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

1791 my $args = $3;
1792
1793 create_parameterlist($args, ',', $file, $declaration_name);
1794 } else {
1795 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1796 return;
1797 }
1798
1503 output_declaration($declaration_name,
1504 'typedef',
1505 {'typedef' => $declaration_name,
1506 'module' => $modulename,
1507 'sectionlist' => \@sectionlist,
1508 'sections' => \%sections,
1509 'purpose' => $declaration_purpose
1510 });

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

1814 my $args = $3;
1815
1816 create_parameterlist($args, ',', $file, $declaration_name);
1817 } else {
1818 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1819 return;
1820 }
1821
1822 if ($identifier ne $declaration_name) {
1823 print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
1824 return;
1825 }
1826
1799 my $prms = join " ", @parameterlist;
1800 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1801
1802 # This check emits a lot of warnings at the moment, because many
1803 # functions don't have a 'Return' doc section. So until the number
1804 # of warnings goes sufficiently down, the check is only performed in
1805 # verbose mode.
1806 # TODO: always perform the check.

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

1873 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1874 $tracepointargs = $1;
1875 }
1876 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1877 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1878 "$prototype\n";
1879 } else {
1880 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1827 my $prms = join " ", @parameterlist;
1828 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1829
1830 # This check emits a lot of warnings at the moment, because many
1831 # functions don't have a 'Return' doc section. So until the number
1832 # of warnings goes sufficiently down, the check is only performed in
1833 # verbose mode.
1834 # TODO: always perform the check.

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

1901 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1902 $tracepointargs = $1;
1903 }
1904 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1905 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1906 "$prototype\n";
1907 } else {
1908 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1909 $identifier = "trace_$identifier";
1881 }
1882}
1883
1884sub syscall_munge() {
1885 my $void = 0;
1886
1887 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1888## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {

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

2036 }
2037}
2038
2039#
2040# STATE_NAME: Looking for the "name - description" line
2041#
2042sub process_name($$) {
2043 my $file = shift;
1910 }
1911}
1912
1913sub syscall_munge() {
1914 my $void = 0;
1915
1916 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1917## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {

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

2065 }
2066}
2067
2068#
2069# STATE_NAME: Looking for the "name - description" line
2070#
2071sub process_name($$) {
2072 my $file = shift;
2044 my $identifier;
2045 my $descr;
2046
2047 if (/$doc_block/o) {
2048 $state = STATE_DOCBLOCK;
2049 $contents = "";
2050 $new_start_line = $.;
2051
2052 if ( $1 eq "" ) {
2053 $section = $section_intro;
2054 } else {
2055 $section = $1;
2056 }
2073 my $descr;
2074
2075 if (/$doc_block/o) {
2076 $state = STATE_DOCBLOCK;
2077 $contents = "";
2078 $new_start_line = $.;
2079
2080 if ( $1 eq "" ) {
2081 $section = $section_intro;
2082 } else {
2083 $section = $1;
2084 }
2057 }
2058 elsif (/$doc_decl/o) {
2085 } elsif (/$doc_decl/o) {
2059 $identifier = $1;
2086 $identifier = $1;
2060 if (/\s*([\w\s]+?)(\(\))?\s*-/) {
2087 if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
2061 $identifier = $1;
2062 }
2088 $identifier = $1;
2089 }
2090 if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
2091 $decl_type = $1;
2092 $identifier = $2;
2093 } else {
2094 $decl_type = 'function';
2095 $identifier =~ s/^define\s+//;
2096 }
2097 $identifier =~ s/\s+$//;
2063
2064 $state = STATE_BODY;
2065 # if there's no @param blocks need to set up default section
2066 # here
2067 $contents = "";
2068 $section = $section_default;
2069 $new_start_line = $. + 1;
2098
2099 $state = STATE_BODY;
2100 # if there's no @param blocks need to set up default section
2101 # here
2102 $contents = "";
2103 $section = $section_default;
2104 $new_start_line = $. + 1;
2070 if (/-(.*)/) {
2105 if (/[-:](.*)/) {
2071 # strip leading/trailing/multiple spaces
2072 $descr= $1;
2073 $descr =~ s/^\s*//;
2074 $descr =~ s/\s*$//;
2075 $descr =~ s/\s+/ /g;
2076 $declaration_purpose = $descr;
2077 $state = STATE_BODY_MAYBE;
2078 } else {
2079 $declaration_purpose = "";
2080 }
2081
2082 if (($declaration_purpose eq "") && $verbose) {
2083 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2084 print STDERR $_;
2085 ++$warnings;
2086 }
2087
2106 # strip leading/trailing/multiple spaces
2107 $descr= $1;
2108 $descr =~ s/^\s*//;
2109 $descr =~ s/\s*$//;
2110 $descr =~ s/\s+/ /g;
2111 $declaration_purpose = $descr;
2112 $state = STATE_BODY_MAYBE;
2113 } else {
2114 $declaration_purpose = "";
2115 }
2116
2117 if (($declaration_purpose eq "") && $verbose) {
2118 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2119 print STDERR $_;
2120 ++$warnings;
2121 }
2122
2088 if ($identifier =~ m/^struct\b/) {
2089 $decl_type = 'struct';
2090 } elsif ($identifier =~ m/^union\b/) {
2091 $decl_type = 'union';
2092 } elsif ($identifier =~ m/^enum\b/) {
2093 $decl_type = 'enum';
2094 } elsif ($identifier =~ m/^typedef\b/) {
2095 $decl_type = 'typedef';
2096 } else {
2097 $decl_type = 'function';
2123 if ($identifier eq "") {
2124 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2125 print STDERR $_;
2126 ++$warnings;
2127 $state = STATE_NORMAL;
2098 }
2099
2100 if ($verbose) {
2128 }
2129
2130 if ($verbose) {
2101 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2131 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
2102 }
2103 } else {
2104 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2105 " - I thought it was a doc line\n";
2106 ++$warnings;
2107 $state = STATE_NORMAL;
2108 }
2109}

--- 330 unchanged lines hidden --- 		2132 }
2133 } else {
2134 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2135 " - I thought it was a doc line\n";
2136 ++$warnings;
2137 $state = STATE_NORMAL;
2138 }
2139}

--- 330 unchanged lines hidden ---