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.
Showing the changes to scripts (1 of 2 files). Show all
Unified · Split
| @@ -866,48 +866,53 @@ sub output_function_rst(%) { · 865 unmodified lines | |||
| 866 | print "\n"; | 866 | print "\n"; |
| 867 | } | 867 | } |
| 868 | 868 | ||
| 869 | print "**Parameters**\n\n"; | 869 | # |
| 870 | # Put our descriptive text into a container (thus an HTML <div>) to help | ||
| 871 | # set the function prototypes apart. | ||
| 872 | # | ||
| 873 | print ".. container:: kernelindent\n\n"; | ||
| 870 | $lineprefix = " "; | 874 | $lineprefix = " "; |
| 875 | print $lineprefix . "**Parameters**\n\n"; | ||
| 871 | foreach $parameter (@{$args{'parameterlist'}}) { | 876 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 872 | my $parameter_name = $parameter; | 877 | my $parameter_name = $parameter; |
| 873 | $parameter_name =~ s/\[.*//; | 878 | $parameter_name =~ s/\[.*//; |
| 874 | $type = $args{'parametertypes'}{$parameter}; | 879 | $type = $args{'parametertypes'}{$parameter}; |
| 875 | 880 | ||
| 876 | if ($type ne "") { | 881 | if ($type ne "") { |
| 877 | print "``$type``\n"; | 882 | print $lineprefix . "``$type``\n"; |
| 878 | } else { | 883 | } else { |
| 879 | print "``$parameter``\n"; | 884 | print $lineprefix . "``$parameter``\n"; |
| 880 | } | 885 | } |
| 881 | 886 | ||
| 882 | print_lineno($parameterdesc_start_lines{$parameter_name}); | 887 | print_lineno($parameterdesc_start_lines{$parameter_name}); |
| 883 | 888 | ||
| 889 | $lineprefix = " "; | ||
| 884 | if (defined($args{'parameterdescs'}{$parameter_name}) && | 890 | if (defined($args{'parameterdescs'}{$parameter_name}) && |
| 885 | $args{'parameterdescs'}{$parameter_name} ne $undescribed) { | 891 | $args{'parameterdescs'}{$parameter_name} ne $undescribed) { |
| 886 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); | 892 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); |
| 887 | } else { | 893 | } else { |
| 888 | print " *undescribed*\n"; | 894 | print $lineprefix . "*undescribed*\n"; |
| 889 | } | 895 | } |
| 896 | $lineprefix = " "; | ||
| 890 | print "\n"; | 897 | print "\n"; |
| 891 | } | 898 | } |
| 892 | 899 | ||
| 893 | $lineprefix = $oldprefix; | ||
| 894 | output_section_rst(@_); | 900 | output_section_rst(@_); |
| 901 | $lineprefix = $oldprefix; | ||
| 895 | } | 902 | } |
| 896 | 903 | ||
| 897 | sub output_section_rst(%) { | 904 | sub output_section_rst(%) { |
| 898 | my %args = %{$_[0]}; | 905 | my %args = %{$_[0]}; |
| 899 | my $section; | 906 | my $section; |
| 900 | my $oldprefix = $lineprefix; | 907 | my $oldprefix = $lineprefix; |
| 901 | $lineprefix = ""; | ||
| 902 | 908 | ||
| 903 | foreach $section (@{$args{'sectionlist'}}) { | 909 | foreach $section (@{$args{'sectionlist'}}) { |
| 904 | print "**$section**\n\n"; | 910 | print $lineprefix . "**$section**\n\n"; |
| 905 | print_lineno($section_start_lines{$section}); | 911 | print_lineno($section_start_lines{$section}); |
| 906 | output_highlight_rst($args{'sections'}{$section}); | 912 | output_highlight_rst($args{'sections'}{$section}); |
| 907 | print "\n"; | 913 | print "\n"; |
| 908 | } | 914 | } |
| 909 | print "\n"; | 915 | print "\n"; |
| 910 | $lineprefix = $oldprefix; | ||
| 911 | } | 916 | } |
| 912 | 917 | ||
| 913 | sub output_enum_rst(%) { | 918 | sub output_enum_rst(%) { |
| @@ -915,6 +920,7 @@ sub output_enum_rst(%) { · 1 unmodified line | |||
| 915 | my ($parameter); | 920 | my ($parameter); |
| 916 | my $oldprefix = $lineprefix; | 921 | my $oldprefix = $lineprefix; |
| 917 | my $count; | 922 | my $count; |
| 923 | my $outer; | ||
| 918 | 924 | ||
| 919 | if ($sphinx_major < 3) { | 925 | if ($sphinx_major < 3) { |
| 920 | my $name = "enum " . $args{'enum'}; | 926 | my $name = "enum " . $args{'enum'}; |
| @@ -924,22 +930,25 @@ sub output_enum_rst(%) { · 3 unmodified lines | |||
| 924 | print "\n\n.. c:enum:: " . $name . "\n\n"; | 930 | print "\n\n.. c:enum:: " . $name . "\n\n"; |
| 925 | } | 931 | } |
| 926 | print_lineno($declaration_start_line); | 932 | print_lineno($declaration_start_line); |
| 927 | $lineprefix = " "; | 933 | $lineprefix = " "; |
| 928 | output_highlight_rst($args{'purpose'}); | 934 | output_highlight_rst($args{'purpose'}); |
| 929 | print "\n"; | 935 | print "\n"; |
| 930 | 936 | ||
| 931 | print "**Constants**\n\n"; | 937 | print ".. container:: kernelindent\n\n"; |
| 932 | $lineprefix = " "; | 938 | $outer = $lineprefix . " "; |
| 939 | $lineprefix = $outer . " "; | ||
| 940 | print $outer . "**Constants**\n\n"; | ||
| 933 | foreach $parameter (@{$args{'parameterlist'}}) { | 941 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 934 | print "``$parameter``\n"; | 942 | print $outer . "``$parameter``\n"; |
| 943 | |||
| 935 | if ($args{'parameterdescs'}{$parameter} ne $undescribed) { | 944 | if ($args{'parameterdescs'}{$parameter} ne $undescribed) { |
| 936 | output_highlight_rst($args{'parameterdescs'}{$parameter}); | 945 | output_highlight_rst($args{'parameterdescs'}{$parameter}); |
| 937 | } else { | 946 | } else { |
| 938 | print " *undescribed*\n"; | 947 | print $lineprefix . "*undescribed*\n"; |
| 939 | } | 948 | } |
| 940 | print "\n"; | 949 | print "\n"; |
| 941 | } | 950 | } |
| 942 | 951 | print "\n"; | |
| 943 | $lineprefix = $oldprefix; | 952 | $lineprefix = $oldprefix; |
| 944 | output_section_rst(@_); | 953 | output_section_rst(@_); |
| 945 | } | 954 | } |
| @@ -982,18 +991,19 @@ sub output_struct_rst(%) { · 36 unmodified lines | |||
| 982 | } | 991 | } |
| 983 | } | 992 | } |
| 984 | print_lineno($declaration_start_line); | 993 | print_lineno($declaration_start_line); |
| 985 | $lineprefix = " "; | 994 | $lineprefix = " "; |
| 986 | output_highlight_rst($args{'purpose'}); | 995 | output_highlight_rst($args{'purpose'}); |
| 987 | print "\n"; | 996 | print "\n"; |
| 988 | 997 | ||
| 989 | print "**Definition**\n\n"; | 998 | print ".. container:: kernelindent\n\n"; |
| 990 | print "::\n\n"; | 999 | print $lineprefix . "**Definition**::\n\n"; |
| 991 | my $declaration = $args{'definition'}; | 1000 | my $declaration = $args{'definition'}; |
| 992 | $declaration =~ s/\t/ /g; | 1001 | $lineprefix = $lineprefix . " "; |
| 993 | print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; | 1002 | $declaration =~ s/\t/$lineprefix/g; |
| 1003 | print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n"; | ||
| 994 | 1004 | ||
| 995 | print "**Members**\n\n"; | ||
| 996 | $lineprefix = " "; | 1005 | $lineprefix = " "; |
| 1006 | print $lineprefix . "**Members**\n\n"; | ||
| 997 | foreach $parameter (@{$args{'parameterlist'}}) { | 1007 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 998 | ($parameter =~ /^#/) && next; | 1008 | ($parameter =~ /^#/) && next; |
| 999 | 1009 | ||
| @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { · 3 unmodified lines | |||
| 1003 | ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; | 1013 | ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; |
| 1004 | $type = $args{'parametertypes'}{$parameter}; | 1014 | $type = $args{'parametertypes'}{$parameter}; |
| 1005 | print_lineno($parameterdesc_start_lines{$parameter_name}); | 1015 | print_lineno($parameterdesc_start_lines{$parameter_name}); |
| 1006 | print "``" . $parameter . "``\n"; | 1016 | print $lineprefix . "``" . $parameter . "``\n"; |
| 1017 | $lineprefix = " "; | ||
| 1007 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); | 1018 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); |
| 1019 | $lineprefix = " "; | ||
| 1008 | print "\n"; | 1020 | print "\n"; |
| 1009 | } | 1021 | } |
| 1010 | print "\n"; | 1022 | print "\n"; |