iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve the HTML formatting of kerneldoc comments

Browse Source 
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: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet 2022-09-30 11:52:09 -06:00
parent df19817f3f
commit eaf710ceb5
2 changed files with 48 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Documentation/sphinx-static/custom.css
View File

@ -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; }

54
scripts/kernel-doc
View File

@ -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'};
@ -924,22 +930,25 @@ sub output_enum_rst(%) {
print "\n\n.. c:enum:: " . $name . "\n\n";
}
print_lineno($declaration_start_line);
$lineprefix = " ";
$lineprefix = " ";
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(@_);
}
@ -982,18 +991,19 @@ sub output_struct_rst(%) {
}
}
print_lineno($declaration_start_line);
$lineprefix = " ";
$lineprefix = " ";
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";