commit 82801d065b4915d030e7f63212d146a75042aa91
author Mauro Carvalho Chehab <mchehab@s-opensource.com> Tue Aug 30 20:20:58 2016 -0300
committer Jonathan Corbet <corbet@lwn.net> Thu Sep 01 08:10:07 2016 -0600
tree 1b518cb58acd5eb1fcd9aad2320394a5725b4522
parent d37c43ce1975c1c3f28064bf3ebd2876e177bad8

docs-rst: kernel-doc: fix typedef output in RST format

When using a typedef function like this one:
	typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);

The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.

So, a declaration like:

	.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)

Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.

So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:

	./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc

So, change the kernel-doc script to produce a RST output for the
above typedef as:
	.. c:type:: v4l2_check_dv_timings_fnc

	   **Typedef**: timings check callback

	**Syntax**

	  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

scripts/kernel-doc

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ad6d4e4..301bf87 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1831,13 +1831,22 @@
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $oldprefix = $lineprefix;
-    my $start;
+    my $start = "";
 
-    print ".. c:function:: ";
-    if ($args{'functiontype'} ne "") {
-	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
+    if ($args{'typedef'}) {
+	print ".. c:type:: ". $args{'function'} . "\n\n";
+	print_lineno($declaration_start_line);
+	print "   **Typedef**: ";
+	$lineprefix = "";
+	output_highlight_rst($args{'purpose'});
+	$start = "\n\n**Syntax**\n\n  ``";
     } else {
-	$start = $args{'function'} . " (";
+	print ".. c:function:: ";
+    }
+    if ($args{'functiontype'} ne "") {
+	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
+    } else {
+	$start .= $args{'function'} . " (";
     }
     print $start;
 
@@ -1856,11 +1865,15 @@
 	    print $type . " " . $parameter;
 	}
     }
-    print ")\n\n";
-    print_lineno($declaration_start_line);
-    $lineprefix = "   ";
-    output_highlight_rst($args{'purpose'});
-    print "\n";
+    if ($args{'typedef'}) {
+	print ");``\n\n";
+    } else {
+	print ")\n\n";
+	print_lineno($declaration_start_line);
+	$lineprefix = "   ";
+	output_highlight_rst($args{'purpose'});
+	print "\n";
+    }
 
     print "**Parameters**\n\n";
     $lineprefix = "  ";
@@ -2203,6 +2216,7 @@
 	output_declaration($declaration_name,
 			   'function',
 			   {'function' => $declaration_name,
+			    'typedef' => 1,
 			    'module' => $modulename,
 			    'functiontype' => $return_type,
 			    'parameterlist' => \@parameterlist,