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

docs: improve the HTML formatting of kerneldoc comments 



Make a few changes to cause functions documented by kerneldoc to stand out
better in the rendered documentation.  Specifically, change kernel-doc to
put the description section into a ".. container::" section, then add a bit
of CSS to indent that section relative to the function prototype (or struct
or enum definition).  Tweak a few other CSS parameters while in the
neighborhood to improve the formatting.

Acked-by: default avatarMauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent df19817f

Documentation/sphinx-static/custom.css

+15 −1
Original line number Diff line number Diff line
@@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; } 


/* Tighten up the layout slightly */

div.body { padding: 0 15px 0 10px; }

div.document { margin: 20px 10px 0 10px; }

div.sphinxsidebarwrapper { padding: 1em 0.4em; }

/* Tweak document margins and don't force width */

div.document {

    margin: 20px 10px 0 10px; 

    width: auto;

}



/*

 * Parameters for the display of function prototypes and such included

 * from C source files.

 */

dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }

/* indent lines 2+ of multi-line function prototypes */

dl.function dt { margin-left: 10em; text-indent: -10em; }

dt.sig-object { font-size: larger; }

div.kernelindent { margin-left: 2em; margin-right: 4em; }

scripts/kernel-doc

+33 −21
Original line number Diff line number Diff line
@@ -866,48 +866,53 @@ sub output_function_rst(%) { 
	print "\n";

    }



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

    #

    # Put our descriptive text into a container (thus an HTML <div>) to help

    # set the function prototypes apart.

    #

    print ".. container:: kernelindent\n\n";

    $lineprefix = "  ";

    print $lineprefix . "**Parameters**\n\n";

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

	my $parameter_name = $parameter;

	$parameter_name =~ s/\[.*//;

	$type = $args{'parametertypes'}{$parameter};



	if ($type ne "") {

	    print "``$type``\n";

	    print $lineprefix . "``$type``\n";

	} else {

	    print "``$parameter``\n";

	    print $lineprefix . "``$parameter``\n";

	}



        print_lineno($parameterdesc_start_lines{$parameter_name});



	$lineprefix = "    ";

	if (defined($args{'parameterdescs'}{$parameter_name}) &&

	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {

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

	} else {

	    print "  *undescribed*\n";

	    print $lineprefix . "*undescribed*\n";

	}

	$lineprefix = "  ";

	print "\n";

    }



    $lineprefix = $oldprefix;

    output_section_rst(@_);

    $lineprefix = $oldprefix;

}



sub output_section_rst(%) {

    my %args = %{$_[0]};

    my $section;

    my $oldprefix = $lineprefix;

    $lineprefix = "";



    foreach $section (@{$args{'sectionlist'}}) {

	print "**$section**\n\n";

	print $lineprefix . "**$section**\n\n";

        print_lineno($section_start_lines{$section});

	output_highlight_rst($args{'sections'}{$section});

	print "\n";

    }

    print "\n";

    $lineprefix = $oldprefix;

}



sub output_enum_rst(%) {
@@ -915,6 +920,7 @@ sub output_enum_rst(%) { 
    my ($parameter);

    my $oldprefix = $lineprefix;

    my $count;

    my $outer;



    if ($sphinx_major < 3) {

	my $name = "enum " . $args{'enum'};
@@ -928,18 +934,21 @@ sub output_enum_rst(%) { 
    output_highlight_rst($args{'purpose'});

    print "\n";



    print "**Constants**\n\n";

    $lineprefix = "  ";

    print ".. container:: kernelindent\n\n";

    $outer = $lineprefix . "  ";

    $lineprefix = $outer . "  ";

    print $outer . "**Constants**\n\n";

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

	print "``$parameter``\n";

	print $outer . "``$parameter``\n";



	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {

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

	} else {

	    print "  *undescribed*\n";

	    print $lineprefix . "*undescribed*\n";

	}

	print "\n";

    }



    print "\n";

    $lineprefix = $oldprefix;

    output_section_rst(@_);

}
@@ -986,14 +995,15 @@ sub output_struct_rst(%) { 
    output_highlight_rst($args{'purpose'});

    print "\n";



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

    print "::\n\n";

    print ".. container:: kernelindent\n\n";

    print $lineprefix . "**Definition**::\n\n";

    my $declaration = $args{'definition'};

    $declaration =~ s/\t/  /g;

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

    $lineprefix = $lineprefix . "  ";

    $declaration =~ s/\t/$lineprefix/g;

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



    print "**Members**\n\n";

    $lineprefix = "  ";

    print $lineprefix . "**Members**\n\n";

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

	($parameter =~ /^#/) && next;
@@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { 
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

	$type = $args{'parametertypes'}{$parameter};

        print_lineno($parameterdesc_start_lines{$parameter_name});

	print "``" . $parameter . "``\n";

	print $lineprefix . "``" . $parameter . "``\n";

	$lineprefix = "    ";

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

	$lineprefix = "  ";

	print "\n";

    }

    print "\n";