History

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.

Jani Nikula committed 10 years ago

Commit ecbcfba1 parent 6450c891 file · +17 −17Browse files

Showing the changes to scripts (1 of 1 file). Show all

Unified · Split

scripts/kernel-doc+17−17
@@ -1823,23 +1823,23 @@ sub output_function_rst(%) { · 1822 unmodified lines
18231823 output_highlight_rst($args{'purpose'});
18241824 print "\n";
18251825
1826− print ":Parameters:\n\n";
1827− $lineprefix = " ";
1826+ print "**Parameters**\n\n";
1827+ $lineprefix = " ";
18281828 foreach $parameter (@{$args{'parameterlist'}}) {
18291829 my $parameter_name = $parameter;
18301830 #$parameter_name =~ s/\[.*//;
18311831 $type = $args{'parametertypes'}{$parameter};
18321832
18331833 if ($type ne "") {
1834− print " ``$type $parameter``\n";
1834+ print "``$type $parameter``\n";
18351835 } else {
1836− print " ``$parameter``\n";
1836+ print "``$parameter``\n";
18371837 }
18381838 if (defined($args{'parameterdescs'}{$parameter_name}) &&
18391839 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
18401840 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
18411841 } else {
1842− print "\n _undescribed_\n";
1842+ print " _undescribed_\n";
18431843 }
18441844 print "\n";
18451845 }
@@ -1852,10 +1852,10 @@ sub output_section_rst(%) { · 6 unmodified lines
18521852 my %args = %{$_[0]};
18531853 my $section;
18541854 my $oldprefix = $lineprefix;
1855− $lineprefix = " ";
1855+ $lineprefix = "";
18561856
18571857 foreach $section (@{$args{'sectionlist'}}) {
1858− print ":$section:\n\n";
1858+ print "**$section**\n\n";
18591859 output_highlight_rst($args{'sections'}{$section});
18601860 print "\n";
18611861 }
@@ -1875,14 +1875,14 @@ sub output_enum_rst(%) { · 13 unmodified lines
18751875 output_highlight_rst($args{'purpose'});
18761876 print "\n";
18771877
1878− print "..\n\n:Constants:\n\n";
1879− $lineprefix = " ";
1878+ print "**Constants**\n\n";
1879+ $lineprefix = " ";
18801880 foreach $parameter (@{$args{'parameterlist'}}) {
1881− print " `$parameter`\n";
1881+ print "``$parameter``\n";
18821882 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
18831883 output_highlight_rst($args{'parameterdescs'}{$parameter});
18841884 } else {
1885− print " undescribed\n";
1885+ print " _undescribed_\n";
18861886 }
18871887 print "\n";
18881888 }
@@ -1918,12 +1918,12 @@ sub output_struct_rst(%) { · 29 unmodified lines
19181918 output_highlight_rst($args{'purpose'});
19191919 print "\n";
19201920
1921− print ":Definition:\n\n";
1922− print " ::\n\n";
1921+ print "**Definition**\n\n";
1922+ print "::\n\n";
19231923 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
19241924 foreach $parameter (@{$args{'parameterlist'}}) {
19251925 if ($parameter =~ /^#/) {
1926− print " " . "$parameter\n";
1926+ print " " . "$parameter\n";
19271927 next;
19281928 }
19291929
@@ -1944,8 +1944,8 @@ sub output_struct_rst(%) { · 14 unmodified lines
19441944 }
19451945 print " };\n\n";
19461946
1947− print ":Members:\n\n";
1948− $lineprefix = " ";
1947+ print "**Members**\n\n";
1948+ $lineprefix = " ";
19491949 foreach $parameter (@{$args{'parameterlist'}}) {
19501950 ($parameter =~ /^#/) && next;
19511951
@@ -1954,7 +1954,7 @@ sub output_struct_rst(%) { · 2 unmodified lines
19541954
19551955 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
19561956 $type = $args{'parametertypes'}{$parameter};
1957− print " `$type $parameter`" . "\n";
1957+ print "``$type $parameter``\n";
19581958 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
19591959 print "\n";
19601960 }

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t