[PATCH 0/3] Fix kernel-doc parser for typedef functions

[PATCH 0/3] Fix kernel-doc parser for typedef functions

[Mauro Carvalho Chehab]

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

[PATCH 1/3] docs-rst: improve typedef parser

[Mauro Carvalho Chehab]

Improve the parser to handle typedefs like:

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

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index bac0af4fc659..d94870270d8e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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

[PATCH 2/3] docs-rst: kernel-doc: fix typedef output in RST format

[Mauro Carvalho Chehab]

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>
---
 scripts/kernel-doc | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d94870270d8e..091e49167b44 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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

[PATCH 3/3] [media] v4l2-dv-timings.h: let kernel-doc parte the typedef argument

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/media/v4l2-dv-timings.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 65caadf13eec..0a7d9e1fc8c8 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -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

Re: [PATCH 0/3] Fix kernel-doc parser for typedef functions

[Jonathan Corbet]

On Tue, 30 Aug 2016 20:20:56 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> 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

I've just applied them, thanks.

jon