kernel-doc (a6ad93e37e76ec43c9cee6a91dd783fb854c2ff1) kernel-doc (f9bbc12ccb35ac8b3fa01cec1a19cb523a7707c7)
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> ##

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

386my $identifier;
387
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
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> ##

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

386my $identifier;
387
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
394# Specifically:
395# Match @word:
396# @...:
397# @{section-name}:
398# while trying to not match literal block starts like "example::"
399#
394my $doc_sect = $doc_com .
400my $doc_sect = $doc_com .
395 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
401 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
396my $doc_content = $doc_com_body . '(.*)';
397my $doc_block = $doc_com . 'DOC:\s*(.*)?';
398my $doc_inline_start = '^\s*/\*\*\s*$';
399my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
400my $doc_inline_end = '^\s*\*/\s*$';
401my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
402my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
403

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

1196
1197sub dump_union($$) {
1198 dump_struct(@_);
1199}
1200
1201sub dump_struct($$) {
1202 my $x = shift;
1203 my $file = shift;
402my $doc_content = $doc_com_body . '(.*)';
403my $doc_block = $doc_com . 'DOC:\s*(.*)?';
404my $doc_inline_start = '^\s*/\*\*\s*$';
405my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
406my $doc_inline_end = '^\s*\*/\s*$';
407my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
408my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
409

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

1202
1203sub dump_union($$) {
1204 dump_struct(@_);
1205}
1206
1207sub dump_struct($$) {
1208 my $x = shift;
1209 my $file = shift;
1210 my $decl_type;
1211 my $members;
1212 my $type = qr{struct|union};
1213 # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
1214 my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*};
1204
1215
1205 if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
1206 my $decl_type = $1;
1216 if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1217 $decl_type = $1;
1207 $declaration_name = $2;
1218 $declaration_name = $2;
1208 my $members = $3;
1219 $members = $3;
1220 } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1221 $decl_type = $1;
1222 $declaration_name = $3;
1223 $members = $2;
1224 }
1209
1225
1226 if ($members) {
1210 if ($identifier ne $declaration_name) {
1211 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
1212 return;
1213 }
1214
1215 # ignore members marked private:
1216 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1217 $members =~ s/\/\*\s*private:.*//gosi;

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

1396 $members = $1;
1397 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1398 $declaration_name = $1;
1399 $members = $2;
1400 }
1401
1402 if ($members) {
1403 if ($identifier ne $declaration_name) {
1227 if ($identifier ne $declaration_name) {
1228 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
1229 return;
1230 }
1231
1232 # ignore members marked private:
1233 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1234 $members =~ s/\/\*\s*private:.*//gosi;

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

1413 $members = $1;
1414 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1415 $declaration_name = $1;
1416 $members = $2;
1417 }
1418
1419 if ($members) {
1420 if ($identifier ne $declaration_name) {
1404 print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1421 if ($identifier eq "") {
1422 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
1423 } else {
1424 print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
1425 }
1405 return;
1406 }
1426 return;
1427 }
1428 $declaration_name = "(anonymous)" if ($declaration_name eq "");
1407
1408 my %_members;
1409
1410 $members =~ s/\s+$//;
1411
1412 foreach my $arg (split ',', $members) {
1413 $arg =~ s/^\s*(\w+).*/$1/;
1414 push @parameterlist, $arg;

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

1750 $prototype =~ s/^asmlinkage +//;
1751 $prototype =~ s/^inline +//;
1752 $prototype =~ s/^__inline__ +//;
1753 $prototype =~ s/^__inline +//;
1754 $prototype =~ s/^__always_inline +//;
1755 $prototype =~ s/^noinline +//;
1756 $prototype =~ s/__init +//;
1757 $prototype =~ s/__init_or_module +//;
1429
1430 my %_members;
1431
1432 $members =~ s/\s+$//;
1433
1434 foreach my $arg (split ',', $members) {
1435 $arg =~ s/^\s*(\w+).*/$1/;
1436 push @parameterlist, $arg;

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

1772 $prototype =~ s/^asmlinkage +//;
1773 $prototype =~ s/^inline +//;
1774 $prototype =~ s/^__inline__ +//;
1775 $prototype =~ s/^__inline +//;
1776 $prototype =~ s/^__always_inline +//;
1777 $prototype =~ s/^noinline +//;
1778 $prototype =~ s/__init +//;
1779 $prototype =~ s/__init_or_module +//;
1780 $prototype =~ s/__flatten +//;
1758 $prototype =~ s/__meminit +//;
1759 $prototype =~ s/__must_check +//;
1760 $prototype =~ s/__weak +//;
1761 $prototype =~ s/__sched +//;
1762 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1763 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1781 $prototype =~ s/__meminit +//;
1782 $prototype =~ s/__must_check +//;
1783 $prototype =~ s/__weak +//;
1784 $prototype =~ s/__sched +//;
1785 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1786 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1787 $prototype =~ s/__attribute_const__ +//;
1764 $prototype =~ s/__attribute__\s*\(\(
1765 (?:
1766 [\w\s]++ # attribute name
1767 (?:\([^)]*+\))? # attribute arguments
1768 \s*+,? # optional comma at the end
1769 )+
1770 \)\)\s+//x;
1771

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

2080
2081 if ( $1 eq "" ) {
2082 $section = $section_intro;
2083 } else {
2084 $section = $1;
2085 }
2086 } elsif (/$doc_decl/o) {
2087 $identifier = $1;
1788 $prototype =~ s/__attribute__\s*\(\(
1789 (?:
1790 [\w\s]++ # attribute name
1791 (?:\([^)]*+\))? # attribute arguments
1792 \s*+,? # optional comma at the end
1793 )+
1794 \)\)\s+//x;
1795

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

2104
2105 if ( $1 eq "" ) {
2106 $section = $section_intro;
2107 } else {
2108 $section = $1;
2109 }
2110 } elsif (/$doc_decl/o) {
2111 $identifier = $1;
2088 if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
2112 my $is_kernel_comment = 0;
2113 my $decl_start = qr{\s*\*};
2114 # test for pointer declaration type, foo * bar() - desc
2115 my $fn_type = qr{\w+\s*\*\s*};
2116 my $parenthesis = qr{\(\w*\)};
2117 my $decl_end = qr{[-:].*};
2118 if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
2089 $identifier = $1;
2090 }
2091 if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
2092 $decl_type = $1;
2093 $identifier = $2;
2119 $identifier = $1;
2120 }
2121 if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
2122 $decl_type = $1;
2123 $identifier = $2;
2094 } else {
2124 $is_kernel_comment = 1;
2125 }
2126 # Look for foo() or static void foo() - description; or misspelt
2127 # identifier
2128 elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
2129 /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) {
2130 $identifier = $1;
2095 $decl_type = 'function';
2096 $identifier =~ s/^define\s+//;
2131 $decl_type = 'function';
2132 $identifier =~ s/^define\s+//;
2133 $is_kernel_comment = 1;
2097 }
2098 $identifier =~ s/\s+$//;
2099
2100 $state = STATE_BODY;
2101 # if there's no @param blocks need to set up default section
2102 # here
2103 $contents = "";
2104 $section = $section_default;

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

2110 $descr =~ s/\s*$//;
2111 $descr =~ s/\s+/ /g;
2112 $declaration_purpose = $descr;
2113 $state = STATE_BODY_MAYBE;
2114 } else {
2115 $declaration_purpose = "";
2116 }
2117
2134 }
2135 $identifier =~ s/\s+$//;
2136
2137 $state = STATE_BODY;
2138 # if there's no @param blocks need to set up default section
2139 # here
2140 $contents = "";
2141 $section = $section_default;

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

2147 $descr =~ s/\s*$//;
2148 $descr =~ s/\s+/ /g;
2149 $declaration_purpose = $descr;
2150 $state = STATE_BODY_MAYBE;
2151 } else {
2152 $declaration_purpose = "";
2153 }
2154
2155 if (!$is_kernel_comment) {
2156 print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
2157 print STDERR $_;
2158 ++$warnings;
2159 $state = STATE_NORMAL;
2160 }
2161
2118 if (($declaration_purpose eq "") && $verbose) {
2119 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2120 print STDERR $_;
2121 ++$warnings;
2122 }
2123
2162 if (($declaration_purpose eq "") && $verbose) {
2163 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2164 print STDERR $_;
2165 ++$warnings;
2166 }
2167
2124 if ($identifier eq "") {
2168 if ($identifier eq "" && $decl_type ne "enum") {
2125 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2126 print STDERR $_;
2127 ++$warnings;
2128 $state = STATE_NORMAL;
2129 }
2130
2131 if ($verbose) {
2132 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";

--- 338 unchanged lines hidden --- 		2169 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
2170 print STDERR $_;
2171 ++$warnings;
2172 $state = STATE_NORMAL;
2173 }
2174
2175 if ($verbose) {
2176 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";

--- 338 unchanged lines hidden ---