Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1400074

[PATCH 3/9] kernel-doc: use rst C domain directives and references for types

Show all headers | View raw

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>
---
 scripts/kernel-doc | 19 +++++++++----------
 1 file 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";
-- 
2.1.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 0/9] kernel-doc/docproc prep work for reStructuredText Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 5/9] docproc: reduce unnecessary indentation Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 2/9] kernel-doc: produce RestructuredText output Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 4/9] docproc: add variables for subcommand and filename Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 9/9] docproc: print a comment about autogeneration for rst output Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 3/9] kernel-doc: use rst C domain directives and references for types Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 7/9] docproc: abstract terminating lines at first space Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 6/9] docproc: abstract docproc directive detection Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  [PATCH 1/9] kernel-doc: rewrite usage description, remove duplicated comments Jani Nikula <jani.nikula@intel.com> - 2016-05-12 15:20 +0200
  Re: [PATCH 0/9] kernel-doc/docproc prep work for reStructuredText Jonathan Corbet <corbet@lwn.net> - 2016-05-14 18:10 +0200

csiph-web