On Fri, 03 Jun 2016, Daniel Vetter <daniel.vetter@xxxxxxxx> wrote:
> 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.
I've tested this, and again, no changes to the html output or the build
output except for fixed line number changes. It's really awesome.
However, there's still a bug somewhere that we're hunting that causes
#define LINENO 0 to be output from kernel-doc in some cases.
Once we have this covered, I intend to send the patch bomb on the lists.
BR,
Jani.
>
> Cc: Jani Nikula <jani.nikula@xxxxxxxxx>
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxx>
> ---
> scripts/kernel-doc | 38 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 38 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 4da6f952d18b..b5961221277b 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 {
> @@ -2833,6 +2868,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 +2902,7 @@ sub process_file($) {
> dump_section($file, $section, xml_escape($contents));
> $section = $section_default;
> $contents = "";
> + $new_start_line = $.;
> } else {
> $contents .= "\n";
> }
> @@ -2900,6 +2937,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") {
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
