From a746fe32cd362c8bba523a97123129ede4f5b75a Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Thu, 25 Feb 2021 20:20:33 +0530 Subject: scripts: kernel-doc: fix typedef support for struct/union parsing Currently, there are ~1290 occurrences in 447 files in the kernel tree 'typedef struct/union' syntax for defining some struct/union. However, kernel-doc currently does not support that syntax. Of the ~1290 occurrences, there are four occurrences in ./include/linux/zstd.h with typedef struct/union syntax and a preceding kernel-doc; all other occurrences have no preceding kernel-doc. Add support for parsing struct/union following this syntax. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210225145033.11431-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8b5bc7bf4bb8..68df17877384 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1201,12 +1201,23 @@ sub dump_union($$) { sub dump_struct($$) { my $x = shift; my $file = shift; + my $decl_type; + my $members; + my $type = qr{struct|union}; + # For capturing struct/union definition body, i.e. "{members*}qualifiers*" + my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*}; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { - my $decl_type = $1; + if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { + $decl_type = $1; $declaration_name = $2; - my $members = $3; + $members = $3; + } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) { + $decl_type = $1; + $declaration_name = $3; + $members = $2; + } + if ($members) { 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; -- cgit v1.2.3 From 084aa00162bda02bcab501c2b0a0ea9252d291b2 Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Sat, 6 Mar 2021 17:05:10 +0530 Subject: scripts: kernel-doc: fix attribute capture in function parsing Currently, kernel-doc warns for function prototype parsing on the presence of attributes "__attribute_const__" and "__flatten" in the definition. There are 166 occurrences in ~70 files in the kernel tree for "__attribute_const__" and 5 occurrences in 4 files for "__flatten". Out of 166, there are 3 occurrences in three different files with "__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in ./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other occurrences have no preceding kernel-doc. Add support for "__attribute_const__" and "__flatten" attributes. A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals that no additional warning or error has been added or removed by the fix. Suggested-by: Lukas Bulwahn Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210306113510.31023-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 68df17877384..e1e562b2e2e7 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1766,12 +1766,14 @@ sub dump_function($$) { $prototype =~ s/^noinline +//; $prototype =~ s/__init +//; $prototype =~ s/__init_or_module +//; + $prototype =~ s/__flatten +//; $prototype =~ s/__meminit +//; $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; $prototype =~ s/__sched +//; $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added + $prototype =~ s/__attribute_const__ +//; $prototype =~ s/__attribute__\s*\(\( (?: [\w\s]++ # attribute name -- cgit v1.2.3 From 0b54c2e34be7987b5e0ffc0aa0e7dced7301cc1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 3 Mar 2021 09:42:14 +0100 Subject: scripts/kernel-doc: ignore identifier on anonymous enums When anonymous enums are used, the identifier is empty. While, IMO, it should be avoided the usage of such enums, adding support for it is not hard. So, postpone the check for empty identifiers to happen only at the dump phase. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/055ad57879f1b9381b90879e00f72fde1c3a5647.1614760910.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e1e562b2e2e7..cb92d0e1e932 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1412,9 +1412,14 @@ 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"; + if ($identifier eq "") { + print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; + } else { + print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + } return; } + $declaration_name = "(anonymous)" if ($declaration_name eq ""); my %_members; @@ -2134,7 +2139,7 @@ sub process_name($$) { ++$warnings; } - if ($identifier eq "") { + if ($identifier eq "" && $decl_type ne "enum") { print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; print STDERR $_; ++$warnings; -- cgit v1.2.3 From 8d295fbad687a61eaa0cf14958c284a3ddbf2173 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 19:14:25 +0100 Subject: kernel-doc: better handle '::' sequences Right now, if one of the following headers end with a '::', the kernel-doc script will do the wrong thing: description|context|returns?|notes?|examples? The real issue is with examples, as people could try to write something like: example:: /* Some C code */ and this won't be properly evaluated. So, improve the regex to not catch '\w+::' regex for the above identifiers. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb92d0e1e932..0ecd71477a16 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -392,7 +392,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; -- cgit v1.2.3 From 212209cff89fe497bc47abcd017aa95e4e8a5196 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 26 Mar 2021 13:16:35 -0600 Subject: docs: kernel-doc: properly recognize parameter lines with colons The previous attempt to properly handle literal blocks broke parsing of parameter lines containing colons; fix it by tweaking the regex to specifically exclude the "::" pattern while accepting lines containing colons in general. Add a little documentation to the regex while in the neighborhood. Reported-by: Stephen Rothwell Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences") Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0ecd71477a16..d6d2b6e0b4eb 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*'; my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names +# Specifically: +# Match @word: +# @...: +# @{section-name}: +# while trying to not match literal block starts like "example::" +# my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; -- cgit v1.2.3 From 3e58e839150db0857dfcb3a0bb3d4af4c6ac1abf Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Mon, 29 Mar 2021 14:59:45 +0530 Subject: 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 Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'scripts/kernel-doc') 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 $_; -- cgit v1.2.3 From f9bbc12ccb35ac8b3fa01cec1a19cb523a7707c7 Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Thu, 15 Apr 2021 00:55:29 +0530 Subject: scripts: kernel-doc: improve parsing for kernel-doc comments syntax Currently kernel-doc does not identify some cases of probable kernel doc comments, for e.g. pointer used as declaration type for identifier, space separated identifier, etc. Some example of these cases in files can be: i)" * journal_t * jbd2_journal_init_dev() - creates and initialises a journal structure" in fs/jbd2/journal.c ii) "* dget, dget_dlock - get a reference to a dentry" in include/linux/dcache.h iii) " * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t" in include/linux/seqlock.h Also improve identification for non-kerneldoc comments. For e.g., i) " * The following functions allow us to read data using a swap map" in kernel/power/swap.c does follow the kernel-doc like syntax, but the content inside does not adheres to the expected format. Improve parsing by adding support for these probable attempts to write kernel-doc comment. Suggested-by: Jonathan Corbet Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com [ jc: fixed some line-length issues ] Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 888913528185..2a85d34fdcd0 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2110,17 +2110,28 @@ sub process_name($$) { } elsif (/$doc_decl/o) { $identifier = $1; my $is_kernel_comment = 0; - if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { + my $decl_start = qr{\s*\*}; + # test for pointer declaration type, foo * bar() - desc + my $fn_type = qr{\w+\s*\*\s*}; + my $parenthesis = qr{\(\w*\)}; + my $decl_end = qr{[-:].*}; + if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) { $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; $is_kernel_comment = 1; } + # Look for foo() or static void foo() - description; or misspelt + # identifier + elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || + /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { + $identifier = $1; + $decl_type = 'function'; + $identifier =~ s/^define\s+//; + $is_kernel_comment = 1; + } $identifier =~ s/\s+$//; $state = STATE_BODY; -- cgit v1.2.3