From 76dd3e7b6650ba5aed96347e685657f80590a7b6 Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Wed, 7 Nov 2018 18:47:12 +0200 Subject: kernel-doc: kill trailing whitespace Signed-off-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ffbe901a37b5..24d3550f7b45 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -361,7 +361,7 @@ 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 -my $doc_sect = $doc_com . +my $doc_sect = $doc_com . '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; @@ -751,7 +751,7 @@ sub output_blockhead_rst(%) { # # Apply the RST highlights to a sub-block of text. -# +# sub highlight_block($) { # The dohighlight kludge requires the text be called $contents my $contents = shift; -- cgit v1.2.3 From bfd228c73090e594efce24fa0f299272bef53c6d Mon Sep 17 00:00:00 2001 From: Mike Rapoport Date: Wed, 7 Nov 2018 18:47:13 +0200 Subject: kernel-doc: extend $type_param to match members referenced by pointer Currently, function parameter description can match '@type.member' expressions but fails to match '@type->member'. Extend the $type_param regex to allow matching both Signed-off-by: Mike Rapoport 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 24d3550f7b45..f9f143145c4b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,7 +212,7 @@ my $anon_struct_union = 0; my $type_constant = '\b``([^\`]+)``\b'; my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; -my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)'; +my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_env = '(\$\w+)'; my $type_enum = '\&(enum\s*([_\w]+))'; -- cgit v1.2.3 From 3d9bfb19bd705f503ac7afc2776d5d56dab88858 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Thu, 22 Nov 2018 13:06:04 +0200 Subject: scripts/kernel-doc: Fix struct and struct field attribute processing The kernel-doc attempts to clear the struct and struct member attributes from the API documentation it produces. It falls short of the job in the following respects: - extra whitespaces are left where __attribute__((...)) was removed, - only a single attribute is removed per struct, - attributes (such as aligned) containing numbers were not removed, - attributes are only cleared from struct fields, not structs themselves. This patch addresses these issues by removing the attributes. Signed-off-by: Sakari Ailus Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f9f143145c4b..c5333d251985 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1062,7 +1062,7 @@ sub dump_struct($$) { my $x = shift; my $file = shift; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}/) { + if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { my $decl_type = $1; $declaration_name = $2; my $members = $3; @@ -1073,8 +1073,9 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; # strip attributes - $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; - $members =~ s/__aligned\s*\([^;]*\)//gos; + $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi; + $members =~ s/\s*__aligned\s*\([^;]*\)//gos; + $members =~ s/\s*__packed\s*//gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; # replace DECLARE_BITMAP $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; -- cgit v1.2.3 From be5cd20c9b491504dfb9105404913de25c47c580 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 11 Jan 2019 12:31:39 -0700 Subject: kernel-doc: suppress 'not described' warnings for embedded struct fields The ability to add kerneldoc comments for fields in embedded structures is useful, but it brought along a whole bunch of warnings for fields that could not be described before. In many cases, there's little value in adding docs for these nested fields, and in cases like: struct a { struct b { int c; } d, e; }; "c" would have to be described twice (as d.c and e.c) to make the warnings go away. We can no doubt do something smarter, but simply suppressing the warnings for this case removes about 70 warnings from the docs build, freeing us to focus on the ones that matter more. So make kerneldoc be silent about missing descriptions for any field containing a ".". 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 c5333d251985..3350e498b4ce 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1474,7 +1474,7 @@ sub push_parameter($$$$) { if (!defined $parameterdescs{$param} && $param !~ /^#/) { $parameterdescs{$param} = $undescribed; - if (show_warnings($type, $declaration_name)) { + if (show_warnings($type, $declaration_name) && $param !~ /\./) { print STDERR "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; ++$warnings; -- cgit v1.2.3