Commit ecbcfba1 authored by Jani Nikula's avatar Jani Nikula
Browse files

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: default avatarJani Nikula <jani.nikula@intel.com>
parent 6450c895

scripts/kernel-doc

+17 −17
Original line number Diff line number Diff line
@@ -1823,7 +1823,7 @@ sub output_function_rst(%) { 
    output_highlight_rst($args{'purpose'});

    print "\n";



    print ":Parameters:\n\n";

    print "**Parameters**\n\n";

    $lineprefix = "  ";

    foreach $parameter (@{$args{'parameterlist'}}) {

	my $parameter_name = $parameter;
@@ -1839,7 +1839,7 @@ sub output_function_rst(%) { 
	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {

	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});

	} else {

	    print "\n        _undescribed_\n";

	    print "  _undescribed_\n";

	}

	print "\n";

    }
@@ -1855,7 +1855,7 @@ sub output_section_rst(%) { 
    $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";

    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,7 +1918,7 @@ sub output_struct_rst(%) { 
    output_highlight_rst($args{'purpose'});

    print "\n";



    print ":Definition:\n\n";

    print "**Definition**\n\n";

    print "::\n\n";

    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";

    foreach $parameter (@{$args{'parameterlist'}}) {
@@ -1944,7 +1944,7 @@ sub output_struct_rst(%) { 
    }

    print "  };\n\n";



    print ":Members:\n\n";

    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";

    }

CRA Git | Maintained and supported by SUSTech CRA and CCSE