diff options
| author | Jonathan Corbet <corbet@lwn.net> | 2022-09-30 11:52:09 -0600 |
|---|---|---|
| committer | Jonathan Corbet <corbet@lwn.net> | 2022-09-30 12:01:23 -0600 |
| commit | 7e473c402adfbf7b9f404573f8f59d024a8a2f64 (patch) | |
| tree | 4d427e5f0fd4728823aaface130ac2211bfad74e /scripts | |
| parent | e4fffa20dd4ce947cb0736ab4f176f463dfaecf6 (diff) | |
| download | lwn-alabaster.tar.gz lwn-alabaster.zip | |
docs: improve the HTML formatting of kerneldoc commentsalabaster
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. Tweak a
few other CSS parameters while in the neighborhood to improve the
formatting.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'scripts')
| -rwxr-xr-x | scripts/kernel-doc | 17 |
1 files changed, 10 insertions, 7 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index aea04365bc69..e5a802b92782 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -866,17 +866,22 @@ 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:: kernelfunc\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}); @@ -890,24 +895,22 @@ sub output_function_rst(%) { 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(%) { |