summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorAditya Srivastava <yashsri421@gmail.com>2021-03-29 14:59:45 +0530
committerJonathan Corbet <corbet@lwn.net>2021-03-29 17:08:28 -0600
commit3e58e839150db0857dfcb3a0bb3d4af4c6ac1abf (patch)
tree97ec9b854b43855dd20ce7cc36afe8b0dd2561d3 /scripts/kernel-doc
parent212209cff89fe497bc47abcd017aa95e4e8a5196 (diff)
scripts: kernel-doc: add warning for comment not following kernel-doc syntax
Currently, kernel-doc start parsing the comment as a kernel-doc comment if it starts with '/**', but does not take into account if the content inside the comment too, adheres with the expected format. This results in unexpected and unclear warnings for the user. E.g., running scripts/kernel-doc -none mm/memcontrol.c emits: "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead" Here kernel-doc parses the corresponding comment as a kernel-doc comment and expects prototype for it in the next lines, and as a result causing this warning. Provide a clearer warning message to the users regarding the same, if the content inside the comment does not follow the kernel-doc expected format. Signed-off-by: Aditya Srivastava <yashsri421@gmail.com> Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc17
1 files changed, 13 insertions, 4 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d6d2b6e0b4eb..888913528185 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2109,15 +2109,17 @@ sub process_name($$) {
}
} elsif (/$doc_decl/o) {
$identifier = $1;
- if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
+ my $is_kernel_comment = 0;
+ if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
$identifier = $1;
+ $decl_type = 'function';
+ $identifier =~ s/^define\s+//;
+ $is_kernel_comment = 1;
}
if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
$decl_type = $1;
$identifier = $2;
- } else {
- $decl_type = 'function';
- $identifier =~ s/^define\s+//;
+ $is_kernel_comment = 1;
}
$identifier =~ s/\s+$//;
@@ -2139,6 +2141,13 @@ sub process_name($$) {
$declaration_purpose = "";
}
+ if (!$is_kernel_comment) {
+ print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
+ print STDERR $_;
+ ++$warnings;
+ $state = STATE_NORMAL;
+ }
+
if (($declaration_purpose eq "") && $verbose) {
print STDERR "${file}:$.: warning: missing initial short description on line:\n";
print STDERR $_;