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
1823 output_highlight_rst($args{'purpose'});1823 output_highlight_rst($args{'purpose'});
1824 print "\n";1824 print "\n";
1825 1825
1826 print ":Parameters:\n\n";1826 print "**Parameters**\n\n";
1827 $lineprefix = " ";1827 $lineprefix = " ";
1828 foreach $parameter (@{$args{'parameterlist'}}) {1828 foreach $parameter (@{$args{'parameterlist'}}) {
1829 my $parameter_name = $parameter;1829 my $parameter_name = $parameter;
1830 #$parameter_name =~ s/\[.*//;1830 #$parameter_name =~ s/\[.*//;
1831 $type = $args{'parametertypes'}{$parameter};1831 $type = $args{'parametertypes'}{$parameter};
1832 1832
1833 if ($type ne "") {1833 if ($type ne "") {
1834 print " ``$type $parameter``\n";1834 print "``$type $parameter``\n";
1835 } else {1835 } else {
1836 print " ``$parameter``\n";1836 print "``$parameter``\n";
1837 }1837 }
1838 if (defined($args{'parameterdescs'}{$parameter_name}) &&1838 if (defined($args{'parameterdescs'}{$parameter_name}) &&
1839 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {1839 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1840 output_highlight_rst($args{'parameterdescs'}{$parameter_name});1840 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1841 } else {1841 } else {
1842 print "\n _undescribed_\n";1842 print " _undescribed_\n";
1843 }1843 }
1844 print "\n";1844 print "\n";
1845 }1845 }
@@ -1852,10 +1852,10 @@ sub output_section_rst(%) { · 6 unmodified lines
1852 my %args = %{$_[0]};1852 my %args = %{$_[0]};
1853 my $section;1853 my $section;
1854 my $oldprefix = $lineprefix;1854 my $oldprefix = $lineprefix;
1855 $lineprefix = " ";1855 $lineprefix = "";
1856 1856
1857 foreach $section (@{$args{'sectionlist'}}) {1857 foreach $section (@{$args{'sectionlist'}}) {
1858 print ":$section:\n\n";1858 print "**$section**\n\n";
1859 output_highlight_rst($args{'sections'}{$section});1859 output_highlight_rst($args{'sections'}{$section});
1860 print "\n";1860 print "\n";
1861 }1861 }
@@ -1875,14 +1875,14 @@ sub output_enum_rst(%) { · 13 unmodified lines
1875 output_highlight_rst($args{'purpose'});1875 output_highlight_rst($args{'purpose'});
1876 print "\n";1876 print "\n";
1877 1877
1878 print "..\n\n:Constants:\n\n";1878 print "**Constants**\n\n";
1879 $lineprefix = " ";1879 $lineprefix = " ";
1880 foreach $parameter (@{$args{'parameterlist'}}) {1880 foreach $parameter (@{$args{'parameterlist'}}) {
1881 print " `$parameter`\n";1881 print "``$parameter``\n";
1882 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {1882 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1883 output_highlight_rst($args{'parameterdescs'}{$parameter});1883 output_highlight_rst($args{'parameterdescs'}{$parameter});
1884 } else {1884 } else {
1885 print " undescribed\n";1885 print " _undescribed_\n";
1886 }1886 }
1887 print "\n";1887 print "\n";
1888 }1888 }
@@ -1918,12 +1918,12 @@ sub output_struct_rst(%) { · 29 unmodified lines
1918 output_highlight_rst($args{'purpose'});1918 output_highlight_rst($args{'purpose'});
1919 print "\n";1919 print "\n";
1920 1920
1921 print ":Definition:\n\n";1921 print "**Definition**\n\n";
1922 print " ::\n\n";1922 print "::\n\n";
1923 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";1923 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1924 foreach $parameter (@{$args{'parameterlist'}}) {1924 foreach $parameter (@{$args{'parameterlist'}}) {
1925 if ($parameter =~ /^#/) {1925 if ($parameter =~ /^#/) {
1926 print " " . "$parameter\n";1926 print " " . "$parameter\n";
1927 next;1927 next;
1928 }1928 }
1929 1929
@@ -1944,8 +1944,8 @@ sub output_struct_rst(%) { · 14 unmodified lines
1944 }1944 }
1945 print " };\n\n";1945 print " };\n\n";
1946 1946
1947 print ":Members:\n\n";1947 print "**Members**\n\n";
1948 $lineprefix = " ";1948 $lineprefix = " ";
1949 foreach $parameter (@{$args{'parameterlist'}}) {1949 foreach $parameter (@{$args{'parameterlist'}}) {
1950 ($parameter =~ /^#/) && next;1950 ($parameter =~ /^#/) && next;
1951 1951
@@ -1954,7 +1954,7 @@ sub output_struct_rst(%) { · 2 unmodified lines
1954 1954
1955 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;1955 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1956 $type = $args{'parametertypes'}{$parameter};1956 $type = $args{'parametertypes'}{$parameter};
1957 print " `$type $parameter`" . "\n";1957 print "``$type $parameter``\n";
1958 output_highlight_rst($args{'parameterdescs'}{$parameter_name});1958 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1959 print "\n";1959 print "\n";
1960 }1960 }

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