Fix kernel-doc parser for typedef functions

The kernel-doc parser has two issues when handling typedef functions:

1) its parse is incomplete;
2) it causes warnings when a typedef is used as a function argument.

This series partially addresses (1), adding one extra syntax for the parser. I'm pretty sure that the parser is still incomplete and that we'll get some other places where it fails.

Jon,

My plan is to apply the last patch on my tree, together with a series of patches that I'm writing to fix the warnings on nitpick mode.

The other two patches better fit on your tree, IMHO.

Mauro Carvalho Chehab (3):
docs-rst: improve typedef parser
docs-rst: kernel-doc: fix typedef output in RST format [media] v4l2-dv-timings.h: let kernel-doc parte the typedef argument

 include/media/v4l2-dv-timings.h |  4 ++--
 scripts/kernel-doc              | 36 ++++++++++++++++++++++++++----------
 2 files changed, 28 insertions(+), 12 deletions(-)

2.7.4

Improve the parser to handle typedefs like:

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

---
 scripts/kernel-doc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index bac0af4fc659..d94870270d8e 100755
@@ -2191,7 +2191,9 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
+    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+
 	# Function typedefs
 	$return_type = $1;
 	$declaration_name = $2;

2.7.4

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);``

---
 scripts/kernel-doc | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

index d94870270d8e..091e49167b44 100755
@@ -1831,13 +1831,22 @@ sub output_function_rst(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $oldprefix = $lineprefix;
-    my $start;
+    my $start = "";
 
-    print ".. c: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 {
+	print ".. c:function:: ";
+    }
     if ($args{'functiontype'} ne "") {
-	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
+	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
     } else {
-	$start = $args{'function'} . " (";
+	$start .= $args{'function'} . " (";
     }
     print $start;
 

@@ -1857,11 +1866,15 @@ sub output_function_rst(%) {
 	    $count++;
 	}
     }
-    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 = "  ";

@@ -2204,6 +2217,7 @@ sub dump_typedef($$) {
 	output_declaration($declaration_name,
 			   'function',
 			   {'function' => $declaration_name,
+			    'typedef' => 1,
 			    'module' => $modulename,
 			    'functiontype' => $return_type,
 			    'parameterlist' => \@parameterlist,

2.7.4

Now that scripts/kernel-doc was fixed to parse the typedef argument used here, let it produce documentation.

---
 include/media/v4l2-dv-timings.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 65caadf13eec..0a7d9e1fc8c8 100644
@@ -28,8 +28,8 @@
  */
 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
 
-/*
- * v4l2_check_dv_timings_fnc - timings check callback
+/**
+ * typedef v4l2_check_dv_timings_fnc - timings check callback
  *
  * @t: the v4l2_dv_timings struct.
  * @handle: a handle from the driver.

2.7.4

I've just applied them, thanks.

jon