From 02a4f4fe522c29bcd4a61e094f7fe8d64f00ee06 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 2 Jan 2017 16:22:23 +0100 Subject: kernel-doc: cleanup parameter type in function-typed arguments A prototype like /** * foo - sample definition * @bar: a parameter */ int foo(int (*bar)(int x, int y)); is currently producing .. c:function:: int foo (int (*bar) (int x, int y) sample definition **Parameters** ``int (*)(int x, int y) bar`` a parameter Collapse the spaces so that the output is nicer. Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 030fc633acd4..c1ea91c2e497 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2409,6 +2409,7 @@ sub push_parameter($$$) { # "[blah" in a parameter string; ###$param =~ s/\s*//g; push @parameterlist, $param; + $type =~ s/\s\s+/ /g; $parametertypes{$param} = $type; } -- cgit v1.2.3 From b1aaa546b52baf7cdc97961e9ba445a26948c1af Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 2 Jan 2017 16:22:24 +0100 Subject: kernel-doc: strip attributes even if they have an argument An inline function can have an attribute, as in include/linux/log2.h, and kernel-doc handles this already for simple cases. However, some attributes have arguments (e.g. the "target" attribute). Handle those too. Furthermore, attributes could be at the beginning of a function declaration, before the return type. To correctly handle this case, you need to strip spaces after the attributes; otherwise, dump_function is left confused. Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c1ea91c2e497..99b4847f9bb2 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2506,7 +2506,13 @@ sub dump_function($$) { $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added - $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//; + $prototype =~ s/__attribute__\s*\(\( + (?: + [\w\s]++ # attribute name + (?:\([^)]*+\))? # attribute arguments + \s*+,? # optional comma at the end + )+ + \)\)\s+//x; # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) -- cgit v1.2.3 From fc6d7af89fa968c378d4437d7905ccd76efa6af4 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 2 Jan 2017 16:22:25 +0100 Subject: kernel-doc: include parameter type in docbook output The restructuredText output includes both the parameter type and the name for functions and function-typed members. Do the same for docbook. Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 99b4847f9bb2..5476cf4f4673 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1131,8 +1131,9 @@ sub output_function_xml(%) { foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; + $type = $args{'parametertypes'}{$parameter}; - print " \n $parameter\n"; + print " \n $type $parameter\n"; print " \n \n"; $lineprefix=" "; output_highlight($args{'parameterdescs'}{$parameter_name}); @@ -1223,8 +1224,9 @@ sub output_struct_xml(%) { defined($args{'parameterdescs'}{$parameter_name}) || next; ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; print " "; - print " $parameter\n"; + print " $type $parameter\n"; print " \n"; output_highlight($args{'parameterdescs'}{$parameter_name}); print " \n"; -- cgit v1.2.3 From 5267dd354bcd267f76d0f97193fe8a93899f8986 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 2 Jan 2017 16:22:26 +0100 Subject: kernel-doc: make member highlighting available in all backends Note that, in order to produce the correct Docbook markup, the "." or "->" must be separated from the member name in the regex's captured fields. For consistency, this change is applied to $type_member and $type_member_func too, not just to $type_member_xml. List mode only prints the struct name, to avoid any undesired change in the operation of docproc. Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 5476cf4f4673..d5e9f765b4fc 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -199,12 +199,12 @@ EOF # 'funcname()' - function # '$ENVVAR' - environmental variable # '&struct_name' - name of a structure (up to two words including 'struct') +# '&struct_name.member' - name of a structure member # '@parameter' - name of a parameter # '%CONST' - name of a constant. ## init lots of data - my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; @@ -221,7 +221,8 @@ my $type_enum_full = '\&(enum)\s*([_\w]+)'; my $type_struct_full = '\&(struct)\s*([_\w]+)'; my $type_typedef_full = '\&(typedef)\s*([_\w]+)'; my $type_union_full = '\&(union)\s*([_\w]+)'; -my $type_member = '\&([_\w]+)((\.|->)[_\w]+)'; +my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; +my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)'; my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. @@ -233,7 +234,8 @@ my @highlights_html = ( [$type_func, "\$1"], [$type_struct_xml, "\$1"], [$type_env, "\$1"], - [$type_param, "\$1"] + [$type_param, "\$1"], + [$type_member_xml, "\$1\$2\$3"] ); my $local_lt = "\\\\\\\\lt:"; my $local_gt = "\\\\\\\\gt:"; @@ -245,7 +247,8 @@ my @highlights_html5 = ( [$type_func, "\$1"], [$type_struct_xml, "\$1"], [$type_env, "\$1"], - [$type_param, "\$1]"] + [$type_param, "\$1]"], + [$type_member_xml, "\$1\$2\$3"] ); my $blankline_html5 = $local_lt . "br /" . $local_gt; @@ -256,7 +259,8 @@ my @highlights_xml = ( [$type_struct_xml, "\$1"], [$type_param, "\$1"], [$type_func, "\$1"], - [$type_env, "\$1"] + [$type_env, "\$1"], + [$type_member_xml, "\$1\$2\$3"] ); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; @@ -266,7 +270,8 @@ my @highlights_gnome = ( [$type_func, "\$1"], [$type_struct, "\$1"], [$type_env, "\$1"], - [$type_param, "\$1" ] + [$type_param, "\$1" ], + [$type_member, "\$1\$2\$3"] ); my $blankline_gnome = "\n"; @@ -275,7 +280,8 @@ my @highlights_man = ( [$type_constant, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], - [$type_param, "\\\\fI\$1\\\\fP"] + [$type_param, "\\\\fI\$1\\\\fP"], + [$type_member, "\\\\fI\$1\$2\$3\\\\fP"] ); my $blankline_man = ""; @@ -284,7 +290,8 @@ my @highlights_text = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], - [$type_param, "\$1"] + [$type_param, "\$1"], + [$type_member, "\$1\$2\$3"] ); my $blankline_text = ""; @@ -292,8 +299,8 @@ my $blankline_text = ""; my @highlights_rst = ( [$type_constant, "``\$1``"], # Note: need to escape () to avoid func matching later - [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"], - [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], + [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], + [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], @@ -311,7 +318,8 @@ my @highlights_list = ( [$type_constant, "\$1"], [$type_func, "\$1"], [$type_struct, "\$1"], - [$type_param, "\$1"] + [$type_param, "\$1"], + [$type_member, "\$1"] ); my $blankline_list = ""; -- cgit v1.2.3 From df31175bb4d372b99410034a8ac23ae5526f49d2 Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Mon, 2 Jan 2017 16:22:27 +0100 Subject: kernel-doc: make highlights more homogenous for the various backends $type_struct_full and friends are only used by the restructuredText backend, because it needs to separate enum/struct/typedef/union from the name of the type. However, $type_struct is *also* used by the rST backend. This is confusing. This patch replaces $type_struct's use in the rST backend with a new $type_fallback; it modifies $type_struct so that it can be used in the rST backend; and creates regular expressions like $type_struct for enum/typedef/union, for use in all backends. Note that, compared to $type_*_full, in the new regexes $1 includes both the "kind" and the name (before, $1 was pretty much a constant). Signed-off-by: Paolo Bonzini Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 68 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 18 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d5e9f765b4fc..4c9ada36fe6b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -214,15 +214,19 @@ my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params -my $type_struct = '\&((struct\s*)*[_\w]+)'; -my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; -my $type_enum_full = '\&(enum)\s*([_\w]+)'; -my $type_struct_full = '\&(struct)\s*([_\w]+)'; -my $type_typedef_full = '\&(typedef)\s*([_\w]+)'; -my $type_union_full = '\&(union)\s*([_\w]+)'; +my $type_enum = '\&(enum\s*([_\w]+))'; +my $type_struct = '\&(struct\s*([_\w]+))'; +my $type_typedef = '\&(typedef\s*([_\w]+))'; +my $type_union = '\&(union\s*([_\w]+))'; my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback = '\&([_\w]+)'; +my $type_enum_xml = '\&(enum\s*([_\w]+))'; +my $type_struct_xml = '\&(struct\s*([_\w]+))'; +my $type_typedef_xml = '\&(typedef\s*([_\w]+))'; +my $type_union_xml = '\&(union\s*([_\w]+))'; my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)'; +my $type_fallback_xml = '\&([_\w]+)'; my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. @@ -232,10 +236,14 @@ my $type_member_func = $type_member . '\(\)'; my @highlights_html = ( [$type_constant, "\$1"], [$type_func, "\$1"], + [$type_enum_xml, "\$1"], [$type_struct_xml, "\$1"], + [$type_typedef_xml, "\$1"], + [$type_union_xml, "\$1"], [$type_env, "\$1"], [$type_param, "\$1"], - [$type_member_xml, "\$1\$2\$3"] + [$type_member_xml, "\$1\$2\$3"], + [$type_fallback_xml, "\$1"] ); my $local_lt = "\\\\\\\\lt:"; my $local_gt = "\\\\\\\\gt:"; @@ -245,10 +253,14 @@ my $blankline_html = $local_lt . "p" . $local_gt; # was "

" my @highlights_html5 = ( [$type_constant, "\$1"], [$type_func, "\$1"], + [$type_enum_xml, "\$1"], [$type_struct_xml, "\$1"], + [$type_typedef_xml, "\$1"], + [$type_union_xml, "\$1"], [$type_env, "\$1"], [$type_param, "\$1]"], - [$type_member_xml, "\$1\$2\$3"] + [$type_member_xml, "\$1\$2\$3"], + [$type_fallback_xml, "\$1"] ); my $blankline_html5 = $local_lt . "br /" . $local_gt; @@ -256,11 +268,15 @@ my $blankline_html5 = $local_lt . "br /" . $local_gt; my @highlights_xml = ( ["([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2"], [$type_constant, "\$1"], + [$type_enum_xml, "\$1"], [$type_struct_xml, "\$1"], + [$type_typedef_xml, "\$1"], + [$type_union_xml, "\$1"], [$type_param, "\$1"], [$type_func, "\$1"], [$type_env, "\$1"], - [$type_member_xml, "\$1\$2\$3"] + [$type_member_xml, "\$1\$2\$3"], + [$type_fallback_xml, "\$1"] ); my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; @@ -268,10 +284,14 @@ my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $loca my @highlights_gnome = ( [$type_constant, "\$1"], [$type_func, "\$1"], + [$type_enum, "\$1"], [$type_struct, "\$1"], + [$type_typedef, "\$1"], + [$type_union, "\$1"], [$type_env, "\$1"], [$type_param, "\$1" ], - [$type_member, "\$1\$2\$3"] + [$type_member, "\$1\$2\$3"], + [$type_fallback, "\$1"] ); my $blankline_gnome = "\n"; @@ -279,9 +299,13 @@ my $blankline_gnome = "\n"; my @highlights_man = ( [$type_constant, "\$1"], [$type_func, "\\\\fB\$1\\\\fP"], + [$type_enum, "\\\\fI\$1\\\\fP"], [$type_struct, "\\\\fI\$1\\\\fP"], + [$type_typedef, "\\\\fI\$1\\\\fP"], + [$type_union, "\\\\fI\$1\\\\fP"], [$type_param, "\\\\fI\$1\\\\fP"], - [$type_member, "\\\\fI\$1\$2\$3\\\\fP"] + [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], + [$type_fallback, "\\\\fI\$1\\\\fP"] ); my $blankline_man = ""; @@ -289,9 +313,13 @@ my $blankline_man = ""; my @highlights_text = ( [$type_constant, "\$1"], [$type_func, "\$1"], + [$type_enum, "\$1"], [$type_struct, "\$1"], + [$type_typedef, "\$1"], + [$type_union, "\$1"], [$type_param, "\$1"], - [$type_member, "\$1\$2\$3"] + [$type_member, "\$1\$2\$3"], + [$type_fallback, "\$1"] ); my $blankline_text = ""; @@ -303,12 +331,12 @@ my @highlights_rst = ( [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\\:c\\:func\\:`\$1()`"], - [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], - [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], - [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], - [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], + [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], # in rst this can refer to any type - [$type_struct, "\\:c\\:type\\:`\$1`"], + [$type_fallback, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] ); my $blankline_rst = "\n"; @@ -317,9 +345,13 @@ my $blankline_rst = "\n"; my @highlights_list = ( [$type_constant, "\$1"], [$type_func, "\$1"], + [$type_enum, "\$1"], [$type_struct, "\$1"], + [$type_typedef, "\$1"], + [$type_union, "\$1"], [$type_param, "\$1"], - [$type_member, "\$1"] + [$type_member, "\$1"], + [$type_fallback, "\$1"] ); my $blankline_list = ""; -- cgit v1.2.3 From ada5f446bbe504ddf5a374cae65b39108db86867 Mon Sep 17 00:00:00 2001 From: Gabriel Krisman Bertazi Date: Mon, 9 Jan 2017 18:11:57 -0200 Subject: kernel-doc: properly document array arguments of function Documentation for array parameters passed in a function, like the first argument in the function below, weren't getting exported in the rst format, although they work fine for html and pdf formats: void drm_clflush_pages(struct page * pages[], unsigned long num_pages) That's because the string key to store the description in the parameterdescs dictionary doesn't have the [] suffix. This cleans up the suffix from the key before accessing the dictionary. Signed-off-by: Gabriel Krisman Bertazi Fixes: c0d1b6ee780a ("kernel-doc: produce RestructuredText output") Reviewed-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4c9ada36fe6b..03875d788ea8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1925,7 +1925,7 @@ sub output_function_rst(%) { $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; - #$parameter_name =~ s/\[.*//; + $parameter_name =~ s/\[.*//; $type = $args{'parametertypes'}{$parameter}; if ($type ne "") { -- cgit v1.2.3 From 5a0bc578e0723b71ecb19f5796d0b0f937785d92 Mon Sep 17 00:00:00 2001 From: Matthew Wilcox Date: Mon, 23 Jan 2017 00:18:10 -0800 Subject: kernel-doc: Handle returning pointers to pointers Clearly nobody ever tried to build the documentation for the radix tree before: include/linux/radix-tree.h:400: warning: cannot understand function prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter, unsigned long start) ' Indeed, the regexes only handled a single '*', not one-or-more. I have tried to fix that, but now I have perl regexes all over my hands, and I fear I shall never be clean again. Signed-off-by: Matthew Wilcox Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 03875d788ea8..33c85dfdfce9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2582,21 +2582,21 @@ sub dump_function($$) { $noret = 1; } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { $return_type = $1; $declaration_name = $2; my $args = $3; -- cgit v1.2.3