summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-05-12 16:15:38 +0300
committerJonathan Corbet <corbet@lwn.net>2016-05-14 09:56:34 -0600
commit6285097654725f39357527b553d03b70bfbaf4d2 (patch)
tree33f1519fb1360fb2de6605654c6b8c8cce443377
parentc0d1b6ee780ab16f16cdbe046aa9c83a2a31f9e2 (diff)
kernel-doc: use rst C domain directives and references for types
First, the headings for structs, enums and typedefs will be similar to functions. Second, this provides a kind of namespace for cross references. Third, and most importantly, the return and parameter types from .. c:function:: definitions will automagically become cross references to the documented types. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-rwxr-xr-xscripts/kernel-doc19
1 files changed, 9 insertions, 10 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ad1fb0e3031..2fc8fad5195e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -275,9 +275,9 @@ my $blankline_text = "";
my @highlights_rst = (
[$type_constant, "``\$1``"],
[$type_func, "\\:c\\:func\\:`\$1`"],
- [$type_struct_full, "\\:ref\\:`\$1 \$2`"],
- [$type_enum_full, "\\:ref\\:`\$1 \$2`"],
- [$type_struct, "\\:ref\\:`struct \$1`"],
+ [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+ [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+ [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
[$type_param, "**\$1**"]
);
my $blankline_rst = "\n";
@@ -1835,10 +1835,9 @@ sub output_enum_rst(%) {
my %args = %{$_[0]};
my ($parameter);
my $count;
-
my $name = "enum " . $args{'enum'};
- print ".. _" . $name . ":\n\n";
- print "**$name**\n\n";
+
+ print "\n\n.. c:type:: " . $name . "\n\n";
print " " . $args{'purpose'} . "\n\n";
print "..\n\n:Constants:\n\n";
@@ -1863,8 +1862,9 @@ sub output_typedef_rst(%) {
my $count;
my $name = "typedef " . $args{'typedef'};
- print "**$name**\n\n";
- print $args{'purpose'} . "\n\n";
+ ### FIXME: should the name below contain "typedef" or not?
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ print " " . $args{'purpose'} . "\n\n";
output_section_rst(@_);
}
@@ -1874,8 +1874,7 @@ sub output_struct_rst(%) {
my ($parameter);
my $name = $args{'type'} . " " . $args{'struct'};
- print ".. _" . $name . ":\n\n";
- print "**$name**\n\n";
+ print "\n\n.. c:type:: " . $name . "\n\n";
print " " . $args{'purpose'} . "\n\n";
print ":Definition:\n\n";