scripts/kernel-doc: update script from Linux 5.2
cover scripts/kernel-doc: update script from Linux 5.2
Avoid some warnings when running 'make htmldocs'.
Correctly generate documentation for functions with function pointers as paramaters.
Heinrich Schuchardt (2):
scripts/kernel-doc: update script from Linux 5.2 scripts/kernel-doc: fix parsing of function pointers
scripts/kernel-doc | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-)
--
2.20.1
PATCH 1/2 scripts/kernel-doc: update script from Linux 5.2
Update the script from Linux 5.2 to avoid some warnings.
--- scripts/kernel-doc | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-)
scripts/kernel-doc +19 -18
@@ -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]+))';
@@ -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;
@@ -1148,20 +1149,20 @@ sub dump_struct($$) { } } } - $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/; + $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/; } # Ignore other nested elements, like enums - $members =~ s/({[^\{\}]*})//g; + $members =~ s/(\{[^\{\}]*\})//g; create_parameterlist($members, ';', $file, $declaration_name); check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); # Adjust declaration for better display - $declaration =~ s/([{;])/$1\n/g; - $declaration =~ s/}\s+;/};/g; + $declaration =~ s/([\{;])/$1\n/g; + $declaration =~ s/\}\s+;/};/g; # Better handle inlined enums - do {} while ($declaration =~ s/(enum\s+{[^}]+),([^\n])/$1,\n$2/); + do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/); my @def_args = split /\n/, $declaration; my $level = 1;
@@ -1171,12 +1172,12 @@ sub dump_struct($$) { $clause =~ s/\s+$//; $clause =~ s/\s+/ /; next if (!$clause); - $level-- if ($clause =~ m/(})/ && $level > 1); + $level-- if ($clause =~ m/(\})/ && $level > 1); if (!($clause =~ m/^\s*#/)) { $declaration .= "\t" x $level; } $declaration .= "\t" . $clause . "\n"; - $level++ if ($clause =~ m/({)/ && !($clause =~m/}/)); + $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/)); } output_declaration($declaration_name, 'struct',
@@ -1244,7 +1245,7 @@ sub dump_enum($$) { # strip #define macros inside enums $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; - if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { + if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) { $declaration_name = $1; my $members = $2; my %_members;
@@ -1473,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;
@@ -1785,7 +1786,7 @@ sub process_proto_type($$) { } while (1) { - if ( $x =~ /([^{};]*)([{};])(.*)/ ) { + if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) { if( length $prototype ) { $prototype .= " " }
@@ -1904,13 +1905,13 @@ sub process_name($$) { ++$warnings; } - if ($identifier =~ m/^struct/) { + if ($identifier =~ m/^struct\b/) { $decl_type = 'struct'; - } elsif ($identifier =~ m/^union/) { + } elsif ($identifier =~ m/^union\b/) { $decl_type = 'union'; - } elsif ($identifier =~ m/^enum/) { + } elsif ($identifier =~ m/^enum\b/) { $decl_type = 'enum'; - } elsif ($identifier =~ m/^typedef/) { + } elsif ($identifier =~ m/^typedef\b/) { $decl_type = 'typedef'; } else { $decl_type = 'function';
--
2.20.1
PATCH 1/2 scripts/kernel-doc: update script from Linux 5.2
Quoted 3 lines · Heinrich Schuchardt
Update the script from Linux 5.2 to avoid some warnings.
Signed-off-by Heinrich Schuchardt <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 819 bytes Desc: not available URL: <http://lists.denx.de/pipermail/u-boot/attachments/20190724/e02564c8/attachment.sig>
PATCH 2/2 scripts/kernel-doc: fix parsing of function pointers
In reply to Heinrich Schuchardtkernel-doc fails to parse function definitions like the one below
efi_status_t efi_create_event(uint32_t type, efi_uintn_t notify_tpl,
void (EFIAPI *notify_function) (
struct efi_event *event, void *context),
void *notify_context, efi_guid_t *group, struct efi_event **event)
{
due to the "EFIAPI" attribute preceding the function name.
cf. https://lkml.org/lkml/2018/9/3/1185
--- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +1 -1
@@ -1382,7 +1382,7 @@ sub create_parameterlist($$$$) { } elsif ($arg =~ m/\(.+\)\s*\(/) { # pointer-to-function $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/; + $arg =~ m/[^\(]+\([\w\s]*\*?\s*([\w\.]*)\s*\)/; $param = $1; $type = $arg; $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
--
2.20.1
PATCH 2/2 scripts/kernel-doc: fix parsing of function pointers
Quoted 10 lines · Heinrich Schuchardt
kernel-doc fails to parse function definitions like the one below
efi_status_tefi_create_event(uint32_t type,efi_uintn_tnotify_tpl,
void (EFIAPI*notify_function) (
structefi_event*event, void *context),
void*notify_context,efi_guid_t*group, structefi_event**event)
{
Quoted 5 lines
due to the "EFIAPI" attribute preceding the function name.
cf. https://lkml.org/lkml/2018/9/3/1185
Signed-off-by Heinrich Schuchardt <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 819 bytes Desc: not available URL: <http://lists.denx.de/pipermail/u-boot/attachments/20190724/a2d33477/attachment.sig>