summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2022-09-30 11:52:09 -0600
committerJonathan Corbet <corbet@lwn.net>2022-10-18 16:29:29 -0600
commiteaf710ceb5ae284778a87c0d0f2348c19e3e4751 (patch)
tree1629c8c63da18b4bd5260c6b4e5ab530078b5eaf /scripts/kernel-doc
parentdf19817f3ff3de28e87139b6d172c0094402e1f2 (diff)
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: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc54
1 files changed, 33 insertions, 21 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index aea04365bc69..11bafc8e85ab 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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";