Commit af250290 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

docs: kernel-doc: Don't mangle literal code blocks in comments 



It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

   if (desperate)
       run_in_circles();

The ".. code-block::" directive can also be used to this end.  kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx.  The result is
unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them.  It's ugly, but that means it fits
in well with the rest of the script.

Reviewed-by: default avatarJani Nikula <jani.nikula@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent c17add56

scripts/kernel-doc

+64 −5
Original line number Diff line number Diff line
@@ -748,14 +748,73 @@ sub output_blockhead_rst(%) { 
    }

}



#

# Apply the RST highlights to a sub-block of text.

#   

sub highlight_block($) {

    # The dohighlight kludge requires the text be called $contents

    my $contents = shift;

    eval $dohighlight;

    die $@ if $@;

    return $contents;

}



#

# Regexes used only here.

#

my $sphinx_literal = '^[^.].*::$';

my $sphinx_cblock = '^\.\.\ +code-block::';



sub output_highlight_rst {

    my $contents = join "\n",@_;

    my $input = join "\n",@_;

    my $output = "";

    my $line;

    my $in_literal = 0;

    my $litprefix;

    my $block = "";



    eval $dohighlight;

    die $@ if $@;

    foreach $line (split "\n",$input) {

	#

	# If we're in a literal block, see if we should drop out

	# of it.  Otherwise pass the line straight through unmunged.

	#

	if ($in_literal) {

	    if (! ($line =~ /^\s*$/)) {

		#

		# If this is the first non-blank line in a literal

		# block we need to figure out what the proper indent is.

		#

		if ($litprefix eq "") {

		    $line =~ /^(\s*)/;

		    $litprefix = '^' . $1;

		    $output .= $line . "\n";

		} elsif (! ($line =~ /$litprefix/)) {

		    $in_literal = 0;

		} else {

		    $output .= $line . "\n";

		}

	    } else {

		$output .= $line . "\n";

	    }

	}

	#

	# Not in a literal block (or just dropped out)

	#

	if (! $in_literal) {

	    $block .= $line . "\n";

	    if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {

		$in_literal = 1;

		$litprefix = "";

		$output .= highlight_block($block);

		$block = ""

	    }

	}

    }



    foreach $line (split "\n", $contents) {

    if ($block) {

	$output .= highlight_block($block);

    }

    foreach $line (split "\n", $output) {

	print $lineprefix . $line . "\n";

    }

}

CRA Git | Maintained and supported by SUSTech CRA and CCSE