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