From 5e64fa9c441ff273f39527f4014d3c3e724d321a Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 19 May 2016 20:32:48 +0300 Subject: kernel-doc/rst: fix use of uninitialized value I'm not quite sure why the errors below are happening, but this fixes them. Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819, line 6494. Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line 1759, line 6494. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 2fc8fad5195e..babb374c043d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1803,7 +1803,8 @@ sub output_function_rst(%) { } else { print " ``$parameter``\n"; } - if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) { + if (defined($args{'parameterdescs'}{$parameter_name}) && + $args{'parameterdescs'}{$parameter_name} ne $undescribed) { my $oldprefix = $lineprefix; $lineprefix = " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); -- cgit v1.2.3 From 86ae2e38d40ed6bf7c907d126053e6f4b1dc5b6e Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 21 Jan 2016 13:05:22 +0200 Subject: kernel-doc: support printing exported and non-exported symbols Currently we use docproc to figure out which symbols are exported, and then docproc calls kernel-doc on specific functions, to get documentation on exported functions. According to git blame and docproc comments, this is due to historical reasons, as functions and their corresponding EXPORT_SYMBOL* may have been in different files. However for more than ten years the recommendation in CodingStyle has been to place the EXPORT_SYMBOL* immediately after the closing function brace line. Additionally, the kernel-doc comments for functions are generally placed above the function definition in the .c files (i.e. where the EXPORT_SYMBOL* is) rather than above the declaration in the .h files. There are some exceptions to this, but AFAICT none of these are included in DocBook documentation using the "!E" docproc directive. Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the function definition, kernel-doc can extract the exported vs. not information by making two passes on the input file. Add support for that via the new -export and -internal parameters. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index babb374c043d..3ad54abe0989 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -59,6 +59,12 @@ Output format selection (mutually exclusive): -text Output plain text format. Output selection (mutually exclusive): + -export Only output documentation for symbols that have been + exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() + in the same FILE. + -internal Only output documentation for symbols that have NOT been + exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() + in the same FILE. -function NAME Only output documentation for the given function(s) or DOC: section title(s). All other functions and DOC: sections are ignored. May be specified multiple times. @@ -380,6 +386,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_split_start = '^\s*/\*\*\s*$'; my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)'; my $doc_split_end = '^\s*\*/\s*$'; +my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; my %constants; my %parameterdescs; @@ -444,6 +451,12 @@ while ($ARGV[0] =~ m/^-(.*)/) { $function_only = 2; $function = shift @ARGV; $function_table{$function} = 1; + } elsif ($cmd eq "-export") { # only exported symbols + $function_only = 3; + %function_table = () + } elsif ($cmd eq "-internal") { # only non-exported symbols + $function_only = 4; + %function_table = () } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { @@ -1971,8 +1984,10 @@ sub output_declaration { my $functype = shift; my $func = "output_${functype}_$output_mode"; if (($function_only==0) || - ( $function_only == 1 && defined($function_table{$name})) || - ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name})))) + ( ($function_only == 1 || $function_only == 3) && + defined($function_table{$name})) || + ( ($function_only == 2 || $function_only == 4) && + !($functype eq "function" && defined($function_table{$name})))) { &$func(@_); $section_counter++; @@ -2675,6 +2690,16 @@ sub process_file($) { return; } + # two passes for -export and -internal + if ($function_only == 3 || $function_only == 4) { + while () { + if (/$export_symbol/o) { + $function_table{$2} = 1; + } + } + seek(IN, 0, 0); + } + $. = 1; $section_counter = 0; -- cgit v1.2.3 From 48af606ad8912f90e1539621a26e86672976d8ae Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 14:56:05 +0300 Subject: kernel-doc: add names for states and substates Make the state machine a bit more readable by adding constants for parser states and inline member documentation parser substates. While at it, rename the "split" documentation to "inline" documentation. No functional changes. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 91 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 43 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3ad54abe0989..cb5fd248ac57 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -350,24 +350,29 @@ my $section_counter = 0; my $lineprefix=""; -# states -# 0 - normal code -# 1 - looking for function name -# 2 - scanning field start. -# 3 - scanning prototype. -# 4 - documentation block -# 5 - gathering documentation outside main block +# Parser states +use constant { + STATE_NORMAL => 0, # normal code + STATE_NAME => 1, # looking for function name + STATE_FIELD => 2, # scanning field start + STATE_PROTO => 3, # scanning prototype + STATE_DOCBLOCK => 4, # documentation block + STATE_INLINE => 5, # gathering documentation outside main block +}; my $state; my $in_doc_sect; -# Split Doc State -# 0 - Invalid (Before start or after finish) -# 1 - Is started (the /** was found inside a struct) -# 2 - The @parameter header was found, start accepting multi paragraph text. -# 3 - Finished (the */ was found) -# 4 - Error - Comment without header was found. Spit a warning as it's not -# proper kernel-doc and ignore the rest. -my $split_doc_state; +# Inline documentation state +use constant { + STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE) + STATE_INLINE_NAME => 1, # looking for member name (@foo:) + STATE_INLINE_TEXT => 2, # looking for member documentation + STATE_INLINE_END => 3, # done + STATE_INLINE_ERROR => 4, # error - Comment without header was found. + # Spit a warning as it's not + # proper kernel-doc and ignore the rest. +}; +my $inline_doc_state; #declaration types: can be # 'function', 'struct', 'union', 'enum', 'typedef' @@ -383,9 +388,9 @@ my $doc_decl = $doc_com . '(\w+)'; my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; -my $doc_split_start = '^\s*/\*\*\s*$'; -my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)'; -my $doc_split_end = '^\s*\*/\s*$'; +my $doc_inline_start = '^\s*/\*\*\s*$'; +my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)'; +my $doc_inline_end = '^\s*\*/\s*$'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; my %constants; @@ -2497,8 +2502,8 @@ sub reset_state { $struct_actual = ""; $prototype = ""; - $state = 0; - $split_doc_state = 0; + $state = STATE_NORMAL; + $inline_doc_state = STATE_INLINE_NA; } sub tracepoint_munge($) { @@ -2707,14 +2712,14 @@ sub process_file($) { while (s/\\\s*$//) { $_ .= ; } - if ($state == 0) { + if ($state == STATE_NORMAL) { if (/$doc_start/o) { - $state = 1; # next line is always the function name + $state = STATE_NAME; # next line is always the function name $in_doc_sect = 0; } - } elsif ($state == 1) { # this line is the function name (always) + } elsif ($state == STATE_NAME) {# this line is the function name (always) if (/$doc_block/o) { - $state = 4; + $state = STATE_DOCBLOCK; $contents = ""; if ( $1 eq "" ) { $section = $section_intro; @@ -2728,7 +2733,7 @@ sub process_file($) { $identifier = $1; } - $state = 2; + $state = STATE_FIELD; if (/-(.*)/) { # strip leading/trailing/multiple spaces $descr= $1; @@ -2766,9 +2771,9 @@ sub process_file($) { print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", " - I thought it was a doc line\n"; ++$warnings; - $state = 0; + $state = STATE_NORMAL; } - } elsif ($state == 2) { # look for head: lines, and include content + } elsif ($state == STATE_FIELD) { # look for head: lines, and include content if (/$doc_sect/o) { $newsection = $1; $newcontents = $2; @@ -2806,7 +2811,7 @@ sub process_file($) { } $prototype = ""; - $state = 3; + $state = STATE_PROTO; $brcount = 0; # print STDERR "end of doc comment, looking for prototype\n"; } elsif (/$doc_content/) { @@ -2834,9 +2839,9 @@ sub process_file($) { print STDERR "${file}:$.: warning: bad line: $_"; ++$warnings; } - } elsif ($state == 5) { # scanning for split parameters + } elsif ($state == STATE_INLINE) { # scanning for inline parameters # First line (state 1) needs to be a @parameter - if ($split_doc_state == 1 && /$doc_split_sect/o) { + if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { $section = $1; $contents = $2; if ($contents ne "") { @@ -2846,37 +2851,37 @@ sub process_file($) { } $contents .= "\n"; } - $split_doc_state = 2; + $inline_doc_state = STATE_INLINE_TEXT; # Documentation block end */ - } elsif (/$doc_split_end/) { + } elsif (/$doc_inline_end/) { if (($contents ne "") && ($contents ne "\n")) { dump_section($file, $section, xml_escape($contents)); $section = $section_default; $contents = ""; } - $state = 3; - $split_doc_state = 0; + $state = STATE_PROTO; + $inline_doc_state = STATE_INLINE_NA; # Regular text } elsif (/$doc_content/) { - if ($split_doc_state == 2) { + if ($inline_doc_state == STATE_INLINE_TEXT) { $contents .= $1 . "\n"; - } elsif ($split_doc_state == 1) { - $split_doc_state = 4; + } elsif ($inline_doc_state == STATE_INLINE_NAME) { + $inline_doc_state = STATE_INLINE_ERROR; print STDERR "Warning(${file}:$.): "; print STDERR "Incorrect use of kernel-doc format: $_"; ++$warnings; } } - } elsif ($state == 3) { # scanning for function '{' (end of prototype) - if (/$doc_split_start/) { - $state = 5; - $split_doc_state = 1; + } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype) + if (/$doc_inline_start/) { + $state = STATE_INLINE; + $inline_doc_state = STATE_INLINE_NAME; } elsif ($decl_type eq 'function') { process_state3_function($_, $file); } else { process_state3_type($_, $file); } - } elsif ($state == 4) { + } elsif ($state == STATE_DOCBLOCK) { # Documentation block if (/$doc_block/) { dump_doc_section($file, $section, xml_escape($contents)); @@ -2907,7 +2912,7 @@ sub process_file($) { %sections = (); @sectionlist = (); $prototype = ""; - $state = 0; + $state = STATE_NORMAL; } elsif (/$doc_content/) { -- cgit v1.2.3 From b6c3f456cfed53e9f06f431270c9dcd52010785e Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sun, 29 May 2016 22:19:35 +0300 Subject: kernel-doc: add names for output selection Make the output selection a bit more readable by adding constants for the various types of output selection. While at it, actually call the variable for choosing what to output $output_selection. No functional changes. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 47 ++++++++++++++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 17 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb5fd248ac57..dd08944b0a6f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -312,7 +312,15 @@ my $no_doc_sections = 0; my @highlights = @highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; -my $function_only = 0; + +use constant { + OUTPUT_ALL => 0, # output all symbols and doc sections + OUTPUT_INCLUDE => 1, # output only specified symbols + OUTPUT_EXCLUDE => 2, # output everything except specified symbols + OUTPUT_EXPORTED => 3, # output exported symbols + OUTPUT_INTERNAL => 4, # output non-exported symbols +}; +my $output_selection = OUTPUT_ALL; my $show_not_found = 0; my @build_time; @@ -449,18 +457,18 @@ while ($ARGV[0] =~ m/^-(.*)/) { } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document $modulename = shift @ARGV; } elsif ($cmd eq "-function") { # to only output specific functions - $function_only = 1; + $output_selection = OUTPUT_INCLUDE; $function = shift @ARGV; $function_table{$function} = 1; - } elsif ($cmd eq "-nofunction") { # to only output specific functions - $function_only = 2; + } elsif ($cmd eq "-nofunction") { # output all except specific functions + $output_selection = OUTPUT_EXCLUDE; $function = shift @ARGV; $function_table{$function} = 1; } elsif ($cmd eq "-export") { # only exported symbols - $function_only = 3; + $output_selection = OUTPUT_EXPORTED; %function_table = () } elsif ($cmd eq "-internal") { # only non-exported symbols - $function_only = 4; + $output_selection = OUTPUT_INTERNAL; %function_table = () } elsif ($cmd eq "-v") { $verbose = 1; @@ -530,15 +538,17 @@ sub dump_doc_section { return; } - if (($function_only == 0) || - ( $function_only == 1 && defined($function_table{$name})) || - ( $function_only == 2 && !defined($function_table{$name}))) + if (($output_selection == OUTPUT_ALL) || + ($output_selection == OUTPUT_INCLUDE && + defined($function_table{$name})) || + ($output_selection == OUTPUT_EXCLUDE && + !defined($function_table{$name}))) { dump_section($file, $name, $contents); output_blockhead({'sectionlist' => \@sectionlist, 'sections' => \%sections, 'module' => $modulename, - 'content-only' => ($function_only != 0), }); + 'content-only' => ($output_selection != OUTPUT_ALL), }); } } @@ -1988,11 +1998,13 @@ sub output_declaration { my $name = shift; my $functype = shift; my $func = "output_${functype}_$output_mode"; - if (($function_only==0) || - ( ($function_only == 1 || $function_only == 3) && - defined($function_table{$name})) || - ( ($function_only == 2 || $function_only == 4) && - !($functype eq "function" && defined($function_table{$name})))) + if (($output_selection == OUTPUT_ALL) || + (($output_selection == OUTPUT_INCLUDE || + $output_selection == OUTPUT_EXPORTED) && + defined($function_table{$name})) || + (($output_selection == OUTPUT_EXCLUDE || + $output_selection == OUTPUT_INTERNAL) && + !($functype eq "function" && defined($function_table{$name})))) { &$func(@_); $section_counter++; @@ -2696,7 +2708,8 @@ sub process_file($) { } # two passes for -export and -internal - if ($function_only == 3 || $function_only == 4) { + if ($output_selection == OUTPUT_EXPORTED || + $output_selection == OUTPUT_INTERNAL) { while () { if (/$export_symbol/o) { $function_table{$2} = 1; @@ -2929,7 +2942,7 @@ sub process_file($) { } if ($initial_section_counter == $section_counter) { print STDERR "${file}:1: warning: no structured comments found\n"; - if (($function_only == 1) && ($show_not_found == 1)) { + if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) { print STDERR " Was looking for '$_'.\n" for keys %function_table; } if ($output_mode eq "xml") { -- cgit v1.2.3 From 9e72184b55df2b5b8ebdcf0470bd43ef32dc518f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sun, 29 May 2016 22:27:35 +0300 Subject: kernel-doc/rst: do not output DOC: section titles for requested ones If the user requests a specific DOC: section by name, do not output its section title. In these cases, the surrounding context already has a heading, and the DOC: section title is only used as an identifier and a heading for clarity in the source file. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index dd08944b0a6f..659d529b99d8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1764,7 +1764,9 @@ sub output_blockhead_rst(%) { my ($parameter, $section); foreach $section (@{$args{'sectionlist'}}) { - print "**$section**\n\n"; + if ($output_selection != OUTPUT_INCLUDE) { + print "**$section**\n\n"; + } output_highlight_rst($args{'sections'}{$section}); print "\n"; } -- cgit v1.2.3 From a19bce6433c2566dd210f4245525c297ca952574 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 11:28:16 +0300 Subject: kernel-doc/rst: reference functions according to C domain spec The Sphinx C domain spec says function references should include the parens (). Signed-off-by: Jani Nikula --- 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 659d529b99d8..e8651d7cf1cd 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -280,7 +280,7 @@ my $blankline_text = ""; # rst-mode my @highlights_rst = ( [$type_constant, "``\$1``"], - [$type_func, "\\:c\\:func\\:`\$1`"], + [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"], -- cgit v1.2.3 From a7291e7e03f8b45a4b028a410063dc94f9bff8c0 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 13:57:06 +0300 Subject: kernel-doc/rst: &foo references are more universal than structs It's possible to use &foo to reference structs, enums, typedefs, etc. in the Sphinx C domain. Thus do not prefix the links with "struct". Signed-off-by: Jani Nikula --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e8651d7cf1cd..e7aa792e7f1b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -283,7 +283,8 @@ my @highlights_rst = ( [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], - [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"], + # in rst this can refer to any type + [$type_struct, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] ); my $blankline_rst = "\n"; -- cgit v1.2.3 From 47ae7aed34ee9017e9eeb2ad066786239456a90f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 13:57:18 +0300 Subject: kernel-doc/rst: add support for &union foo and &typedef foo references Let the user use "&union foo" and "&typedef foo" to reference foo. The difference to using "union &foo", "typedef &foo", or just "&foo" (which are valid too) is that "union" and "typedef" become part of the link text. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e7aa792e7f1b..446c0912395e 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,6 +212,8 @@ 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]+)'; # Output conversion substitutions. # One for each output format @@ -283,6 +285,8 @@ my @highlights_rst = ( [$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>`"], # in rst this can refer to any type [$type_struct, "\\:c\\:type\\:`\$1`"], [$type_param, "**\$1**"] -- cgit v1.2.3 From f3341dcf3bdcd1209b2911f35e4e970b789c4744 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 16:35:02 +0300 Subject: kernel-doc/rst: add support for struct/union/enum member references Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the struct/union/enum foo definition. The members themselves do not currently have anchors to link to, but this is better than nothing, and promotes a universal notation. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 446c0912395e..e0fd14f6d711 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -214,6 +214,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_func = $type_member . '\(\)'; # Output conversion substitutions. # One for each output format @@ -282,6 +284,9 @@ my $blankline_text = ""; # rst-mode 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_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], -- cgit v1.2.3 From 9c9193c49c1f1662b00476b3d0697a1be37c6b08 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 16:56:27 +0300 Subject: kernel-doc/rst: drop redundant unescape in highlighting This bit is already done by xml_unescape() above. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e0fd14f6d711..8f9eac509377 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1796,7 +1796,6 @@ sub output_highlight_rst { if ($line eq "") { print $lineprefix, $blankline; } else { - $line =~ s/\\\\\\/\&/g; print $lineprefix, $line; } print "\n"; -- cgit v1.2.3 From c099ff6989baf286da8eaed5c7b3d18ae60ea2e7 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 17:18:17 +0300 Subject: kernel-doc/rst: highlight function/struct/enum purpose lines too Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose line too. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8f9eac509377..76bad55c031e 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1805,6 +1805,7 @@ sub output_highlight_rst { sub output_function_rst(%) { my %args = %{$_[0]}; my ($parameter, $section); + my $oldprefix = $lineprefix; my $start; print ".. c:function:: "; @@ -1829,9 +1830,13 @@ sub output_function_rst(%) { print $type . " " . $parameter; } } - print ")\n\n " . $args{'purpose'} . "\n\n"; + print ")\n\n"; + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; print ":Parameters:\n\n"; + $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; #$parameter_name =~ s/\[.*//; @@ -1844,15 +1849,14 @@ sub output_function_rst(%) { } if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { - my $oldprefix = $lineprefix; - $lineprefix = " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); - $lineprefix = $oldprefix; } else { print "\n _undescribed_\n"; } print "\n"; } + + $lineprefix = $oldprefix; output_section_rst(@_); } @@ -1874,14 +1878,16 @@ sub output_section_rst(%) { sub output_enum_rst(%) { my %args = %{$_[0]}; my ($parameter); + my $oldprefix = $lineprefix; my $count; my $name = "enum " . $args{'enum'}; print "\n\n.. c:type:: " . $name . "\n\n"; - print " " . $args{'purpose'} . "\n\n"; + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; print "..\n\n:Constants:\n\n"; - my $oldprefix = $lineprefix; $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { print " `$parameter`\n"; @@ -1892,6 +1898,7 @@ sub output_enum_rst(%) { } print "\n"; } + $lineprefix = $oldprefix; output_section_rst(@_); } @@ -1899,23 +1906,29 @@ sub output_enum_rst(%) { sub output_typedef_rst(%) { my %args = %{$_[0]}; my ($parameter); - my $count; + my $oldprefix = $lineprefix; my $name = "typedef " . $args{'typedef'}; ### FIXME: should the name below contain "typedef" or not? print "\n\n.. c:type:: " . $name . "\n\n"; - print " " . $args{'purpose'} . "\n\n"; + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + $lineprefix = $oldprefix; output_section_rst(@_); } sub output_struct_rst(%) { my %args = %{$_[0]}; my ($parameter); + my $oldprefix = $lineprefix; my $name = $args{'type'} . " " . $args{'struct'}; print "\n\n.. c:type:: " . $name . "\n\n"; - print " " . $args{'purpose'} . "\n\n"; + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; print ":Definition:\n\n"; print " ::\n\n"; @@ -1944,6 +1957,7 @@ sub output_struct_rst(%) { print " };\n\n"; print ":Members:\n\n"; + $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =~ /^#/) && next; @@ -1953,13 +1967,12 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print " `$type $parameter`" . "\n"; - my $oldprefix = $lineprefix; - $lineprefix = " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); - $lineprefix = $oldprefix; print "\n"; } print "\n"; + + $lineprefix = $oldprefix; output_section_rst(@_); } -- cgit v1.2.3 From 13901ef27c354e1bab49a30184ae3b96d96e521a Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 08:57:29 +0300 Subject: kernel-doc: do not regard $, %, or & prefixes as special in section names The use of these is confusing in the script, and per this grep, they're not used anywhere anyway: $ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)" While at it, throw out the constants array, nothing is ever put there again. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 76bad55c031e..f795660dfc7b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -396,14 +396,12 @@ my $inline_doc_state; # 'function', 'struct', 'union', 'enum', 'typedef' my $decl_type; -my $doc_special = "\@\%\$\&"; - my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. my $doc_end = '\*/'; my $doc_com = '\s*\*\s*'; my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; -my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; +my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -411,7 +409,6 @@ my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)'; my $doc_inline_end = '^\s*\*/\s*$'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; -my %constants; my %parameterdescs; my @parameterlist; my %sections; @@ -511,11 +508,7 @@ sub dump_section { my $name = shift; my $contents = join "\n", @_; - if ($name =~ m/$type_constant/) { - $name = $1; -# print STDERR "constant section '$1' = '$contents'\n"; - $constants{$name} = $contents; - } elsif ($name =~ m/$type_param/) { + if ($name =~ m/$type_param/) { # print STDERR "parameter def '$1' = '$contents'\n"; $name = $1; $parameterdescs{$name} = $contents; @@ -2528,7 +2521,6 @@ sub dump_function($$) { sub reset_state { $function = ""; - %constants = (); %parameterdescs = (); %parametertypes = (); @parameterlist = (); @@ -2924,7 +2916,6 @@ sub process_file($) { dump_doc_section($file, $section, xml_escape($contents)); $contents = ""; $function = ""; - %constants = (); %parameterdescs = (); %parametertypes = (); @parameterlist = (); @@ -2942,7 +2933,6 @@ sub process_file($) { dump_doc_section($file, $section, xml_escape($contents)); $contents = ""; $function = ""; - %constants = (); %parameterdescs = (); %parametertypes = (); @parameterlist = (); -- cgit v1.2.3 From a0b96c2dbdb2c2511af407a2657d580f16c3b6f1 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 22:04:06 +0300 Subject: kernel-doc: fix wrong code indentation No functional changes. Signed-off-by: Jani Nikula --- 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 f795660dfc7b..c154c3205df1 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2878,7 +2878,7 @@ sub process_file($) { substr($contents, 0, 1) eq "\t") { $contents = substr($contents, 1); } - $contents .= "\n"; + $contents .= "\n"; } $inline_doc_state = STATE_INLINE_TEXT; # Documentation block end */ -- cgit v1.2.3 From 830066a7a317e3e8872cb2d21dd24af0815f51f9 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 22:04:33 +0300 Subject: kernel-doc/rst: blank lines in output are not needed Current approach leads to two blank lines, while one is enough. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c154c3205df1..a89ff3ca366c 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1786,12 +1786,7 @@ sub output_highlight_rst { die $@ if $@; foreach $line (split "\n", $contents) { - if ($line eq "") { - print $lineprefix, $blankline; - } else { - print $lineprefix, $line; - } - print "\n"; + print $lineprefix . $line . "\n"; } } -- cgit v1.2.3 From 6450c8957ee3a8f58191c2ed6c5b71c7b7d1b310 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 22:04:42 +0300 Subject: kernel-doc: strip leading blank lines from inline doc comments The inline member markup allows whitespace lines before the actual documentation starts. Strip the leading blank lines. This improves the rst output. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a89ff3ca366c..e8ea295567a3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2889,6 +2889,10 @@ sub process_file($) { } elsif (/$doc_content/) { if ($inline_doc_state == STATE_INLINE_TEXT) { $contents .= $1 . "\n"; + # nuke leading blank lines + if ($contents =~ /^\s*$/) { + $contents = ""; + } } elsif ($inline_doc_state == STATE_INLINE_NAME) { $inline_doc_state = STATE_INLINE_ERROR; print STDERR "Warning(${file}:$.): "; -- cgit v1.2.3 From ecbcfba126e857de8dd4996fe31fad782dd6bae0 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 26 May 2016 18:30:27 +0300 Subject: kernel-doc/rst: change the output layout Move away from field lists, and simply use **strong emphasis** for section headings on lines of their own. Do not use rst section headings, because their nesting depth depends on the surrounding context, which kernel-doc has no knowledge of. Also, they do not need to end up in any table of contexts or indexes. There are two related immediate benefits. Field lists are typically rendered in two columns, while the new style uses the horizontal width better. With no extra indent on the left, there's no need to be as fussy about it. Field lists are more susceptible to indentation problems than the new style. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e8ea295567a3..4f559de8b173 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1823,23 +1823,23 @@ sub output_function_rst(%) { output_highlight_rst($args{'purpose'}); print "\n"; - print ":Parameters:\n\n"; - $lineprefix = " "; + print "**Parameters**\n\n"; + $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; #$parameter_name =~ s/\[.*//; $type = $args{'parametertypes'}{$parameter}; if ($type ne "") { - print " ``$type $parameter``\n"; + print "``$type $parameter``\n"; } else { - print " ``$parameter``\n"; + print "``$parameter``\n"; } if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); } else { - print "\n _undescribed_\n"; + print " _undescribed_\n"; } print "\n"; } @@ -1852,10 +1852,10 @@ sub output_section_rst(%) { my %args = %{$_[0]}; my $section; my $oldprefix = $lineprefix; - $lineprefix = " "; + $lineprefix = ""; foreach $section (@{$args{'sectionlist'}}) { - print ":$section:\n\n"; + print "**$section**\n\n"; output_highlight_rst($args{'sections'}{$section}); print "\n"; } @@ -1875,14 +1875,14 @@ sub output_enum_rst(%) { output_highlight_rst($args{'purpose'}); print "\n"; - print "..\n\n:Constants:\n\n"; - $lineprefix = " "; + print "**Constants**\n\n"; + $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { - print " `$parameter`\n"; + print "``$parameter``\n"; if ($args{'parameterdescs'}{$parameter} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter}); } else { - print " undescribed\n"; + print " _undescribed_\n"; } print "\n"; } @@ -1918,12 +1918,12 @@ sub output_struct_rst(%) { output_highlight_rst($args{'purpose'}); print "\n"; - print ":Definition:\n\n"; - print " ::\n\n"; + print "**Definition**\n\n"; + print "::\n\n"; print " " . $args{'type'} . " " . $args{'struct'} . " {\n"; foreach $parameter (@{$args{'parameterlist'}}) { if ($parameter =~ /^#/) { - print " " . "$parameter\n"; + print " " . "$parameter\n"; next; } @@ -1944,8 +1944,8 @@ sub output_struct_rst(%) { } print " };\n\n"; - print ":Members:\n\n"; - $lineprefix = " "; + print "**Members**\n\n"; + $lineprefix = " "; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =~ /^#/) && next; @@ -1954,7 +1954,7 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; - print " `$type $parameter`" . "\n"; + print "``$type $parameter``\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; } -- cgit v1.2.3 From 0a7263014b3a0e05b52ccef314e2ccf6f4550a8b Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sat, 28 May 2016 14:50:20 +0300 Subject: kernel-doc: improve handling of whitespace on the first line param description Handle whitespace on the first line of param text as if it was the empty string. There is no need to add the newline in this case. This improves the rst output in particular, where blank lines may be problematic in parameter lists. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4f559de8b173..e93e796b17ce 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2814,11 +2814,11 @@ sub process_file($) { $in_doc_sect = 1; $in_purpose = 0; $contents = $newcontents; + while ((substr($contents, 0, 1) eq " ") || + substr($contents, 0, 1) eq "\t") { + $contents = substr($contents, 1); + } if ($contents ne "") { - while ((substr($contents, 0, 1) eq " ") || - substr($contents, 0, 1) eq "\t") { - $contents = substr($contents, 1); - } $contents .= "\n"; } $section = $newsection; -- cgit v1.2.3 From b7886de43c9f8a19685cd6e81135de63b9529911 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sat, 28 May 2016 00:41:50 +0300 Subject: kernel-doc: strip leading whitespace from continued param descs If a param description spans multiple lines, check any leading whitespace in the first continuation line, and remove same amount of whitespace from following lines. This allows indentation in the multi-line parameter descriptions for aesthetical reasons while not causing accidentally significant indentation in the rst output. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e93e796b17ce..f6f37e71dc08 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2701,6 +2701,7 @@ sub process_file($) { my $in_purpose = 0; my $initial_section_counter = $section_counter; my ($orig_file) = @_; + my $leading_space; if (defined($ENV{'SRCTREE'})) { $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; @@ -2822,6 +2823,7 @@ sub process_file($) { $contents .= "\n"; } $section = $newsection; + $leading_space = undef; } elsif (/$doc_end/) { if (($contents ne "") && ($contents ne "\n")) { dump_section($file, $section, xml_escape($contents)); @@ -2856,7 +2858,19 @@ sub process_file($) { $declaration_purpose .= " " . xml_escape($1); $declaration_purpose =~ s/\s+/ /g; } else { - $contents .= $1 . "\n"; + my $cont = $1; + if ($section =~ m/^@/ || $section eq $section_context) { + if (!defined $leading_space) { + if ($cont =~ m/^(\s+)/) { + $leading_space = $1; + } else { + $leading_space = ""; + } + } + + $cont =~ s/^$leading_space//; + } + $contents .= $cont . "\n"; } } else { # i dont know - bad line? ignore. -- cgit v1.2.3 From d4b08e0cd2d74eb652d580607982d5054dc42991 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sat, 28 May 2016 00:48:17 +0300 Subject: kernel-doc/rst: use *undescribed* instead of _undescribed_ The latter isn't special to rst. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f6f37e71dc08..19cee0cd53a3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1839,7 +1839,7 @@ sub output_function_rst(%) { $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); } else { - print " _undescribed_\n"; + print " *undescribed*\n"; } print "\n"; } @@ -1882,7 +1882,7 @@ sub output_enum_rst(%) { if ($args{'parameterdescs'}{$parameter} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter}); } else { - print " _undescribed_\n"; + print " *undescribed*\n"; } print "\n"; } -- cgit v1.2.3 From cddfe325afedb67a15fbe1a91e82ffed40236413 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sat, 28 May 2016 10:48:37 +0300 Subject: kernel-doc/rst: remove fixme comment Yes, for our purposes the type should contain typedef. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 19cee0cd53a3..425a94be04f6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1897,7 +1897,6 @@ sub output_typedef_rst(%) { my $oldprefix = $lineprefix; my $name = "typedef " . $args{'typedef'}; - ### FIXME: should the name below contain "typedef" or not? print "\n\n.. c:type:: " . $name . "\n\n"; $lineprefix = " "; output_highlight_rst($args{'purpose'}); -- cgit v1.2.3 From f624adef3d0b9975076c1ba7549b81ed19e34437 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sun, 29 May 2016 11:35:28 +0300 Subject: kernel-doc: limit the "section header:" detection to a select few kernel-doc currently identifies anything matching "section header:" (specifically a string of word characters and spaces followed by a colon) as a new section in the documentation comment, and renders the section header accordingly. Unfortunately, this turns all uses of colon into sections, mostly unintentionally. Considering the output, erroneously creating sections when not intended is always worse than erroneously not creating sections when intended. For example, a line with "http://example.com" turns into a "http" heading followed by "//example.com" in normal text style, which is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even if "WARNING" does not turn into a heading. It is virtually impossible to change all the kernel-doc comments, either way. The compromise is to pick the most commonly used and depended on section headers (with variants) and accept them as section headers. The accepted section headers are, case insensitive: * description: * context: * return: * returns: Additionally, case sensitive: * @return: All of the above are commonly used in the kernel-doc comments, and will result in worse output if not identified as section headers. Also, kernel-doc already has some special handling for all of them, so there's nothing particularly controversial in adding more special treatment for them. While at it, improve the whitespace handling surrounding section names. Do not consider the whitespace as part of the name. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 425a94be04f6..20136564f264 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -401,7 +401,8 @@ my $doc_end = '\*/'; my $doc_com = '\s*\*\s*'; my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; -my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)'; +# @params and a strictly limited set of supported section names +my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -417,6 +418,8 @@ my $sectcheck; my $struct_actual; my $contents = ""; + +# the canonical section names. see also $doc_sect above. my $section_default = "Description"; # default section my $section_intro = "Introduction"; my $section = $section_default; @@ -2798,10 +2801,22 @@ sub process_file($) { $state = STATE_NORMAL; } } elsif ($state == STATE_FIELD) { # look for head: lines, and include content - if (/$doc_sect/o) { + if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; + # map the supported section names to the canonical names + if ($newsection =~ m/^description$/i) { + $newsection = $section_default; + } elsif ($newsection =~ m/^context$/i) { + $newsection = $section_context; + } elsif ($newsection =~ m/^returns?$/i) { + $newsection = $section_return; + } elsif ($newsection =~ m/^\@return$/) { + # special: @return is a section, not a param description + $newsection = $section_return; + } + if (($contents ne "") && ($contents ne "\n")) { if (!$in_doc_sect && $verbose) { print STDERR "${file}:$.: warning: contents before sections\n"; -- cgit v1.2.3 From 32217761ee9db0215350dfe1ca4e66f312fb8c54 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sun, 29 May 2016 09:40:44 +0300 Subject: kernel-doc: concatenate contents of colliding sections If there are multiple sections with the same section name, the current implementation results in several sections by the same heading, with the content duplicated from the last section to all. Even if there's the error message, a more graceful approach is to combine all the identically named sections into one, with concatenated contents. With the supported sections already limited to select few, there are massively fewer collisions than there used to be, but this is still useful for e.g. when function parameters are documented in the middle of a documentation comment, with description spread out above and below. (This is not a recommended documentation style, but used in the kernel nonetheless.) We can now also demote the error to a warning. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 20136564f264..3ac4b57ed76a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -524,11 +524,13 @@ sub dump_section { } else { # print STDERR "other section '$name' = '$contents'\n"; if (defined($sections{$name}) && ($sections{$name} ne "")) { - print STDERR "${file}:$.: error: duplicate section name '$name'\n"; - ++$errors; + print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; + ++$warnings; + $sections{$name} .= $contents; + } else { + $sections{$name} = $contents; + push @sectionlist, $name; } - $sections{$name} = $contents; - push @sectionlist, $name; } } -- cgit v1.2.3 From 2f4ad40a05265827848200689094348363027069 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Mon, 30 May 2016 11:21:06 +0300 Subject: kernel-doc: reset contents and section harder If the documentation comment does not have params or sections, the section heading may leak from the previous documentation comment. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3ac4b57ed76a..0eb2e7b5bf10 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2763,6 +2763,8 @@ sub process_file($) { } $state = STATE_FIELD; + $contents = ""; + $section = $section_default; if (/-(.*)/) { # strip leading/trailing/multiple spaces $descr= $1; @@ -2960,6 +2962,7 @@ sub process_file($) { elsif (/$doc_end/) { dump_doc_section($file, $section, xml_escape($contents)); + $section = $section_default; $contents = ""; $function = ""; %parameterdescs = (); -- cgit v1.2.3 From ebff7f929b2a72fa614f5e95fd34c56c82ac9c36 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 1 Jun 2016 23:46:23 +0200 Subject: scripts/kernel-doc: Remove duplicated DOC: start handling Further up in the state machinery we switch from STATE_NAME to STATE_DOCBLOCK when we match /$doc_block/. Which means this block of code here is entirely unreachable, unless there are multiple DOC: sections within a single kernel-doc comment. Getting a list of all the files with more than one DOC: section using $ git grep -c " * DOC:" | grep -v ":1$" and then doing a full audit of them reveals there are no such comment blocks in the kernel. Supporting multiple DOC: sections in a single kernel-doc comment does not seem like a recommended way of doing things anyway, so nuke the code for simplicity. Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter [Jani: amended the commit message] Signed-off-by: Jani Nikula --- scripts/kernel-doc | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0eb2e7b5bf10..9fb26d142a56 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2942,24 +2942,7 @@ sub process_file($) { process_state3_type($_, $file); } } elsif ($state == STATE_DOCBLOCK) { - # Documentation block - if (/$doc_block/) { - dump_doc_section($file, $section, xml_escape($contents)); - $contents = ""; - $function = ""; - %parameterdescs = (); - %parametertypes = (); - @parameterlist = (); - %sections = (); - @sectionlist = (); - $prototype = ""; - if ( $1 eq "" ) { - $section = $section_intro; - } else { - $section = $1; - } - } - elsif (/$doc_end/) + if (/$doc_end/) { dump_doc_section($file, $section, xml_escape($contents)); $section = $section_default; -- cgit v1.2.3 From b7afa92b55043b71a37a2f658553d3e260859859 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 1 Jun 2016 23:46:24 +0200 Subject: scripts/kernel-doc: Also give functions symbolic names state3 = prototype parsing, so name them accordingly. Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Signed-off-by: Jani Nikula --- scripts/kernel-doc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9fb26d142a56..4da6f952d18b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2593,7 +2593,7 @@ sub syscall_munge() { } } -sub process_state3_function($$) { +sub process_proto_function($$) { my $x = shift; my $file = shift; @@ -2623,7 +2623,7 @@ sub process_state3_function($$) { } } -sub process_state3_type($$) { +sub process_proto_type($$) { my $x = shift; my $file = shift; @@ -2937,9 +2937,9 @@ sub process_file($) { $state = STATE_INLINE; $inline_doc_state = STATE_INLINE_NAME; } elsif ($decl_type eq 'function') { - process_state3_function($_, $file); + process_proto_function($_, $file); } else { - process_state3_type($_, $file); + process_proto_type($_, $file); } } elsif ($state == STATE_DOCBLOCK) { if (/$doc_end/) -- cgit v1.2.3 From 0b0f5f29b282b18d26ce698e1aab0267234f77bf Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 3 Jun 2016 22:21:34 +0200 Subject: scripts/kernel-doc: Add option to inject line numbers Opt-in since this wreaks the rst output and must be removed by consumers again. This is useful to adjust the linenumbers for included kernel-doc snippets in shinx. With that sphinx error message will be accurate when there's issues with the rst-ness of the kernel-doc comments. Especially when transitioning a new docbook .tmpl to .rst this is extremely useful, since you can just use your editors compilation quickfix list to accurately jump from error to error. v2: - Also make sure that we filter the LINENO for purpose/at declaration start so it only shows for selected blocks, not all of them (Jani). While at it make it a notch more accurate. - Avoid undefined $lineno issues. I tried filtering these out at the callsite, but Jani spotted more when linting the entire kernel. Unamed unions and similar things aren't stored consistently and end up with an undefined line number (but also no kernel-doc text, just the parameter type). Simplify things and filter undefined line numbers in print_lineno() to catch them all. v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines or any other special sections that directly jump to the description after the "name - purpose" line. Only really possible for functions without parameters. Noticed by Jani. Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Signed-off-by: Jani Nikula --- scripts/kernel-doc | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4da6f952d18b..5192213c5005 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -74,6 +74,8 @@ Output selection (mutually exclusive): Output selection modifiers: -no-doc-sections Do not output DOC: sections. + -enable-lineno Enable output of #define LINENO lines. Only works with + reStructuredText format. Other parameters: -v Verbose output, more warnings and other information. @@ -319,6 +321,7 @@ my $verbose = 0; my $output_mode = "man"; my $output_preformatted = 0; my $no_doc_sections = 0; +my $enable_lineno = 0; my @highlights = @highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; @@ -351,6 +354,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', # CAVEAT EMPTOR! Some of the others I localised may not want to be, which # could cause "use of undefined value" or other bugs. my ($function, %function_table, %parametertypes, $declaration_purpose); +my $declaration_start_line; my ($type, $declaration_name, $return_type); my ($newsection, $newcontents, $prototype, $brcount, %source_map); @@ -411,13 +415,16 @@ my $doc_inline_end = '^\s*\*/\s*$'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; my %parameterdescs; +my %parameterdesc_start_lines; my @parameterlist; my %sections; my @sectionlist; +my %section_start_lines; my $sectcheck; my $struct_actual; my $contents = ""; +my $new_start_line = 0; # the canonical section names. see also $doc_sect above. my $section_default = "Description"; # default section @@ -486,6 +493,8 @@ while ($ARGV[0] =~ m/^-(.*)/) { usage(); } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; + } elsif ($cmd eq '-enable-lineno') { + $enable_lineno = 1; } elsif ($cmd eq '-show-not-found') { $show_not_found = 1; } @@ -503,6 +512,13 @@ sub get_kernel_version() { return $version; } +# +sub print_lineno { + my $lineno = shift; + if ($enable_lineno && defined($lineno)) { + print "#define LINENO " . $lineno . "\n"; + } +} ## # dumps section contents to arrays/hashes intended for that purpose. # @@ -516,11 +532,15 @@ sub dump_section { $name = $1; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} = $new_start_line; + $new_start_line = 0; } elsif ($name eq "@\.\.\.") { # print STDERR "parameter def '...' = '$contents'\n"; $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} = $new_start_line; + $new_start_line = 0; } else { # print STDERR "other section '$name' = '$contents'\n"; if (defined($sections{$name}) && ($sections{$name} ne "")) { @@ -530,6 +550,8 @@ sub dump_section { } else { $sections{$name} = $contents; push @sectionlist, $name; + $section_start_lines{$name} = $new_start_line; + $new_start_line = 0; } } } @@ -1775,6 +1797,7 @@ sub output_blockhead_rst(%) { if ($output_selection != OUTPUT_INCLUDE) { print "**$section**\n\n"; } + print_lineno($section_start_lines{$section}); output_highlight_rst($args{'sections'}{$section}); print "\n"; } @@ -1824,6 +1847,7 @@ sub output_function_rst(%) { } } print ")\n\n"; + print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; @@ -1840,6 +1864,9 @@ sub output_function_rst(%) { } else { print "``$parameter``\n"; } + + print_lineno($parameterdesc_start_lines{$parameter_name}); + if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); @@ -1861,6 +1888,7 @@ sub output_section_rst(%) { foreach $section (@{$args{'sectionlist'}}) { print "**$section**\n\n"; + print_lineno($section_start_lines{$section}); output_highlight_rst($args{'sections'}{$section}); print "\n"; } @@ -1876,6 +1904,7 @@ sub output_enum_rst(%) { my $name = "enum " . $args{'enum'}; print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; @@ -1903,6 +1932,7 @@ sub output_typedef_rst(%) { my $name = "typedef " . $args{'typedef'}; print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; @@ -1918,6 +1948,7 @@ sub output_struct_rst(%) { my $name = $args{'type'} . " " . $args{'struct'}; print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; @@ -1958,6 +1989,7 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; + print_lineno($parameterdesc_start_lines{$parameter_name}); print "``$type $parameter``\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; @@ -2745,11 +2777,14 @@ sub process_file($) { if (/$doc_start/o) { $state = STATE_NAME; # next line is always the function name $in_doc_sect = 0; + $declaration_start_line = $. + 1; } } elsif ($state == STATE_NAME) {# this line is the function name (always) if (/$doc_block/o) { $state = STATE_DOCBLOCK; $contents = ""; + $new_start_line = $. + 1; + if ( $1 eq "" ) { $section = $section_intro; } else { @@ -2763,8 +2798,11 @@ sub process_file($) { } $state = STATE_FIELD; + # if there's no @param blocks need to set up default section + # here $contents = ""; $section = $section_default; + $new_start_line = $. + 1; if (/-(.*)/) { # strip leading/trailing/multiple spaces $descr= $1; @@ -2833,6 +2871,7 @@ sub process_file($) { $in_doc_sect = 1; $in_purpose = 0; $contents = $newcontents; + $new_start_line = $.; while ((substr($contents, 0, 1) eq " ") || substr($contents, 0, 1) eq "\t") { $contents = substr($contents, 1); @@ -2866,6 +2905,7 @@ sub process_file($) { dump_section($file, $section, xml_escape($contents)); $section = $section_default; $contents = ""; + $new_start_line = $.; } else { $contents .= "\n"; } @@ -2900,6 +2940,7 @@ sub process_file($) { if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { $section = $1; $contents = $2; + $new_start_line = $.; if ($contents ne "") { while ((substr($contents, 0, 1) eq " ") || substr($contents, 0, 1) eq "\t") { -- cgit v1.2.3 From 8569de68e79e94cce6709831edd94accb6942ade Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 9 Jun 2016 13:35:05 -0600 Subject: docs: kernel-doc: Add "example" and "note" to the magic section types Lots of kerneldoc entries use "example:" or "note:" as section headers. Until such a time as we can make them use proper markup, make them work as intended. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 5192213c5005..27757c21551a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -406,7 +406,8 @@ 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 . '\s*(\@\w+|description|context|returns?)\s*:(.*)'; +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*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; -- cgit v1.2.3 From 5668604a6cab13dd5385b8c03a7d55bf92ff0496 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Fri, 10 Jun 2016 11:28:13 +0300 Subject: kernel-doc: remove old debug cruft from dump_section() No functional changes. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 3 --- 1 file changed, 3 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 27757c21551a..ac18eb5ed776 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -529,21 +529,18 @@ sub dump_section { my $contents = join "\n", @_; if ($name =~ m/$type_param/) { -# print STDERR "parameter def '$1' = '$contents'\n"; $name = $1; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; $parameterdesc_start_lines{$name} = $new_start_line; $new_start_line = 0; } elsif ($name eq "@\.\.\.") { -# print STDERR "parameter def '...' = '$contents'\n"; $name = "..."; $parameterdescs{$name} = $contents; $sectcheck = $sectcheck . $name . " "; $parameterdesc_start_lines{$name} = $new_start_line; $new_start_line = 0; } else { -# print STDERR "other section '$name' = '$contents'\n"; if (defined($sections{$name}) && ($sections{$name} ne "")) { print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; ++$warnings; -- cgit v1.2.3 From 95b6be9d198d964fafd9cbf1dd4d1968291e255c Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Fri, 10 Jun 2016 11:14:05 +0300 Subject: kernel-doc: do not warn about duplicate default section names Since commit 32217761ee9db0215350dfe1ca4e66f312fb8c54 Author: Jani Nikula Date: Sun May 29 09:40:44 2016 +0300 kernel-doc: concatenate contents of colliding sections we started getting (more) errors on duplicate section names, especially on the default section name "Description": include/net/mac80211.h:3174: warning: duplicate section name 'Description' This is usually caused by a slightly unorthodox placement of parameter descriptions, like in the above case, and kernel-doc resetting back to the default section more than once within a kernel-doc comment. Ignore warnings on the duplicate section name automatically assigned by kernel-doc, and only consider explicitly user assigned duplicate section names an issue. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ac18eb5ed776..710615f3a4ff 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -542,8 +542,11 @@ sub dump_section { $new_start_line = 0; } else { if (defined($sections{$name}) && ($sections{$name} ne "")) { - print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; - ++$warnings; + # Only warn on user specified duplicate section names. + if ($name ne $section_default) { + print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; + ++$warnings; + } $sections{$name} .= $contents; } else { $sections{$name} = $contents; -- cgit v1.2.3 From da9726ecfba202514d984129c3537b028519cdb8 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Tue, 7 Jun 2016 10:29:59 +0300 Subject: kernel-doc: add missing semi-colons in option parsing Signed-off-by: Jani Nikula --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 710615f3a4ff..a6f82c812c15 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -484,10 +484,10 @@ while ($ARGV[0] =~ m/^-(.*)/) { $function_table{$function} = 1; } elsif ($cmd eq "-export") { # only exported symbols $output_selection = OUTPUT_EXPORTED; - %function_table = () + %function_table = (); } elsif ($cmd eq "-internal") { # only non-exported symbols $output_selection = OUTPUT_INTERNAL; - %function_table = () + %function_table = (); } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { -- cgit v1.2.3 From 1ad560e43c911e19751df65dd2af21341d02eac5 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Tue, 7 Jun 2016 10:53:39 +0300 Subject: kernel-doc: abstract filename mapping Reduce duplication in follow-up work. No functional changes. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a6f82c812c15..516d95fcefb7 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2730,26 +2730,35 @@ sub local_unescape($) { return $text; } -sub process_file($) { +sub map_filename($) { my $file; - my $identifier; - my $func; - my $descr; - my $in_purpose = 0; - my $initial_section_counter = $section_counter; my ($orig_file) = @_; - my $leading_space; if (defined($ENV{'SRCTREE'})) { $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; - } - else { + } else { $file = $orig_file; } + if (defined($source_map{$file})) { $file = $source_map{$file}; } + return $file; +} + +sub process_file($) { + my $file; + my $identifier; + my $func; + my $descr; + my $in_purpose = 0; + my $initial_section_counter = $section_counter; + my ($orig_file) = @_; + my $leading_space; + + $file = map_filename($orig_file); + if (!open(IN,"<$file")) { print STDERR "Error: Cannot open file $file\n"; ++$errors; -- cgit v1.2.3 From 88c2b57da4ce3c8b5f849dc5356bdea9e2ed1134 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Tue, 7 Jun 2016 11:00:52 +0300 Subject: kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs If the kernel-doc comments for functions are not in the same file as the EXPORT_SYMBOL statements, the -export and -internal output selections do not work as expected. This is typically the case when the kernel-doc comments are in header files next to the function declarations and the EXPORT_SYMBOL statements are next to the function definitions in the source files. Let the user specify additional source files in which to look for the EXPORT_SYMBOLs using the new -export-file FILE option, which may be given multiple times. The pathological example for this is include/net/mac80211.h, which has all the kernel-doc documentation for the exported functions defined in a plethora of source files net/mac80211/*.c. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 516d95fcefb7..9708a87c7069 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -61,10 +61,10 @@ Output format selection (mutually exclusive): Output selection (mutually exclusive): -export Only output documentation for symbols that have been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in the same FILE. + in the same FILE or any -export-file FILE. -internal Only output documentation for symbols that have NOT been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in the same FILE. + in the same FILE or any -export-file FILE. -function NAME Only output documentation for the given function(s) or DOC: section title(s). All other functions and DOC: sections are ignored. May be specified multiple times. @@ -76,6 +76,9 @@ Output selection modifiers: -no-doc-sections Do not output DOC: sections. -enable-lineno Enable output of #define LINENO lines. Only works with reStructuredText format. + -export-file FILE Specify an additional FILE in which to look for + EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with + -export or -internal. May be specified multiple times. Other parameters: -v Verbose output, more warnings and other information. @@ -336,6 +339,8 @@ use constant { my $output_selection = OUTPUT_ALL; my $show_not_found = 0; +my @export_file_list; + my @build_time; if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { @@ -488,6 +493,9 @@ while ($ARGV[0] =~ m/^-(.*)/) { } elsif ($cmd eq "-internal") { # only non-exported symbols $output_selection = OUTPUT_INTERNAL; %function_table = (); + } elsif ($cmd eq "-export-file") { + my $file = shift @ARGV; + push(@export_file_list, $file); } elsif ($cmd eq "-v") { $verbose = 1; } elsif (($cmd eq "-h") || ($cmd eq "--help")) { @@ -2747,6 +2755,25 @@ sub map_filename($) { return $file; } +sub process_export_file($) { + my ($orig_file) = @_; + my $file = map_filename($orig_file); + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + while () { + if (/$export_symbol/) { + $function_table{$2} = 1; + } + } + + close(IN); +} + sub process_file($) { my $file; my $identifier; @@ -3081,6 +3108,14 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { close(SOURCE_MAP); } +if ($output_selection == OUTPUT_EXPORTED || + $output_selection == OUTPUT_INTERNAL) { + foreach (@export_file_list) { + chomp; + process_export_file($_); + } +} + foreach (@ARGV) { chomp; process_file($_); -- cgit v1.2.3 From c9b2cfb3faece55df7f50b4ab76bc00ac8e06700 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Tue, 7 Jun 2016 11:05:53 +0300 Subject: kernel-doc: unify all EXPORT_SYMBOL scanning to one place Scan all input files for EXPORT_SYMBOLs along with the explicitly specified export files before actually parsing anything. Signed-off-by: Jani Nikula --- scripts/kernel-doc | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9708a87c7069..932b3f34ff06 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -61,10 +61,10 @@ Output format selection (mutually exclusive): Output selection (mutually exclusive): -export Only output documentation for symbols that have been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in the same FILE or any -export-file FILE. + in any input FILE or -export-file FILE. -internal Only output documentation for symbols that have NOT been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in the same FILE or any -export-file FILE. + in any input FILE or -export-file FILE. -function NAME Only output documentation for the given function(s) or DOC: section title(s). All other functions and DOC: sections are ignored. May be specified multiple times. @@ -2792,17 +2792,6 @@ sub process_file($) { return; } - # two passes for -export and -internal - if ($output_selection == OUTPUT_EXPORTED || - $output_selection == OUTPUT_INTERNAL) { - while () { - if (/$export_symbol/o) { - $function_table{$2} = 1; - } - } - seek(IN, 0, 0); - } - $. = 1; $section_counter = 0; @@ -3110,6 +3099,9 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { if ($output_selection == OUTPUT_EXPORTED || $output_selection == OUTPUT_INTERNAL) { + + push(@export_file_list, @ARGV); + foreach (@export_file_list) { chomp; process_export_file($_); -- cgit v1.2.3 From e7ca311e376c81a51ce031c569f336bdadf5ea98 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 15 Jul 2016 10:19:30 +0200 Subject: kernel-doc: Fix up warning output While trying to make gpu docs warning free I stumbled over one output which wasn't following proper compiler error output standards. Fix it up for more quickfix awesomeness. Cc: Jonathan Corbet Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter 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 932b3f34ff06..7388e88a1f50 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2994,7 +2994,7 @@ sub process_file($) { } } elsif ($inline_doc_state == STATE_INLINE_NAME) { $inline_doc_state = STATE_INLINE_ERROR; - print STDERR "Warning(${file}:$.): "; + print STDERR "${file}:$.: warning: "; print STDERR "Incorrect use of kernel-doc format: $_"; ++$warnings; } -- cgit v1.2.3 From a88b1672d4ddf9895eb53e6980926d5e960dea8e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 11:46:36 -0300 Subject: doc-rst: kernel-doc: fix handling of address_space tags The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it: Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration. If the function has no return type: Error in declarator or parameters and qualifiers Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) --------^ If the function has a return type: Error in declarator or parameters and qualifiers If pointer to member declarator: Invalid definition: Expected '::' in pointer to member (function). [error at 37] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) -------------------------------------^ If declarator-id: Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) ------------------------------------------------------------------------------------------------------^ So, we have to remove it from the function prototype. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 7388e88a1f50..4f2e9049e8fa 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1848,6 +1848,10 @@ sub output_function_rst(%) { } $count++; $type = $args{'parametertypes'}{$parameter}; + + # RST doesn't like address_space tags at function prototypes + $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print $1 . $parameter . ") (" . $2; -- cgit v1.2.3