summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2021-01-14 09:04:47 +0100
committerJonathan Corbet <corbet@lwn.net>2021-01-18 13:33:26 -0700
commit52042e2db45290f6a512d525518488b7bf143531 (patch)
tree32e986fa690964afe751ab8ed0aeaea068de2935 /scripts/kernel-doc
parent96c0f7c0b9ac00fff928b9e81d134639a4e4ba56 (diff)
scripts: kernel-doc: validate kernel-doc markup with the actual names
Kernel-doc currently expects that the kernel-doc markup to come just before the function/enum/struct/union/typedef prototype. Yet, if it find things like: /** * refcount_add - add a value to a refcount * @i: the value to add to the refcount * @r: the refcount */ static inline void __refcount_add(int i, refcount_t *r, int *oldp); static inline void refcount_add(int i, refcount_t *r); Kernel-doc will do the wrong thing: foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add' .. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp) add a value to a refcount **Parameters** ``int i`` the value to add to the refcount ``refcount_t *r`` the refcount ``int *oldp`` *undescribed* Basically, it will document "__refcount_add" with the kernel-doc markup for refcount_add. If both functions have the same arguments, this won't even produce any warning! Add a logic to check if the kernel-doc identifier matches the actual name of the C function or data structure that will be documented. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/081546f141a496d6cabb99a4adc140444c705e93.1610610937.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc62
1 files changed, 46 insertions, 16 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6325bec3f66f..a9a92e623dbc 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@ my $inline_doc_state;
# 'function', 'struct', 'union', 'enum', 'typedef'
my $decl_type;
+# Name of the kernel-doc identifier for non-DOC markups
+my $identifier;
+
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+ return;
+ }
+
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) {
}
if ($members) {
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+ return;
+ }
+
my %_members;
$members =~ s/\s+$//;
@@ -1451,6 +1464,11 @@ sub dump_typedef($$) {
my $args = $3;
$return_type =~ s/^\s+//;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ return;
+ }
+
create_parameterlist($args, ',', $file, $declaration_name);
output_declaration($declaration_name,
@@ -1477,6 +1495,11 @@ sub dump_typedef($$) {
if ($x =~ /typedef.*\s+(\w+)\s*;/) {
$declaration_name = $1;
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ return;
+ }
+
output_declaration($declaration_name,
'typedef',
{'typedef' => $declaration_name,
@@ -1796,6 +1819,11 @@ sub dump_function($$) {
return;
}
+ if ($identifier ne $declaration_name) {
+ print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+ return;
+ }
+
my $prms = join " ", @parameterlist;
check_sections($file, $declaration_name, "function", $sectcheck, $prms);
@@ -1878,6 +1906,7 @@ sub tracepoint_munge($) {
"$prototype\n";
} else {
$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+ $identifier = "trace_$identifier";
}
}
@@ -2041,7 +2070,6 @@ sub process_normal() {
#
sub process_name($$) {
my $file = shift;
- my $identifier;
my $descr;
if (/$doc_block/o) {
@@ -2054,12 +2082,19 @@ sub process_name($$) {
} else {
$section = $1;
}
- }
- elsif (/$doc_decl/o) {
+ } elsif (/$doc_decl/o) {
$identifier = $1;
- if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+ if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
$identifier = $1;
}
+ if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
+ $decl_type = $1;
+ $identifier = $2;
+ } else {
+ $decl_type = 'function';
+ $identifier =~ s/^define\s+//;
+ }
+ $identifier =~ s/\s+$//;
$state = STATE_BODY;
# if there's no @param blocks need to set up default section
@@ -2067,7 +2102,7 @@ sub process_name($$) {
$contents = "";
$section = $section_default;
$new_start_line = $. + 1;
- if (/-(.*)/) {
+ if (/[-:](.*)/) {
# strip leading/trailing/multiple spaces
$descr= $1;
$descr =~ s/^\s*//;
@@ -2085,20 +2120,15 @@ sub process_name($$) {
++$warnings;
}
- if ($identifier =~ m/^struct\b/) {
- $decl_type = 'struct';
- } elsif ($identifier =~ m/^union\b/) {
- $decl_type = 'union';
- } elsif ($identifier =~ m/^enum\b/) {
- $decl_type = 'enum';
- } elsif ($identifier =~ m/^typedef\b/) {
- $decl_type = 'typedef';
- } else {
- $decl_type = 'function';
+ if ($identifier eq "") {
+ print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+ print STDERR $_;
+ ++$warnings;
+ $state = STATE_NORMAL;
}
if ($verbose) {
- print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+ print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
}
} else {
print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",