From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752165AbcFDLla (ORCPT ); Sat, 4 Jun 2016 07:41:30 -0400 Received: from mga02.intel.com ([134.134.136.20]:49945 "EHLO mga02.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751237AbcFDLlY (ORCPT ); Sat, 4 Jun 2016 07:41:24 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,417,1459839600"; d="scan'208";a="995120212" From: Jani Nikula To: Jonathan Corbet Cc: Jani Nikula , Markus Heiser , Daniel Vetter , Grant Likely , Mauro Carvalho Chehab , Keith Packard , LKML , linux-doc@vger.kernel.org, Hans Verkuil Subject: [PATCH v2 37/38] scripts/kernel-doc: Add option to inject line numbers Date: Sat, 4 Jun 2016 14:37:38 +0300 Message-Id: <0b0f5f29b282b18d26ce698e1aab0267234f77bf.1465031816.git.jani.nikula@intel.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: References: In-Reply-To: References: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Daniel Vetter 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(+) 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") { -- 2.1.4