[PATCH] scripts/kernel-doc: Add missing close-paren in c:function directives

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print
the close-paren after the argument list of the function pointer
argument. For instance:

 long work_on_cpu(int cpu, long (*fn) (void *, void * arg)

in driver-api/basics.html is missing a ')' separating the
"void *" of the 'fn' arguments from the ", void * arg" which
is an argument to work_on_cpu().

Add the missing close-paren, so that we render the prototype
correctly:

 long work_on_cpu(int cpu, long (*fn)(void *), void * arg)

(Note that Sphinx stops rendering a space between the '(fn*)' and the
'(void *)' once it gets something that's syntactically valid.)

Signed-off-by: Peter Maydell <peter.maydell@xxxxxxxxxx>
---
I noticed this first in the copy of kernel-doc that QEMU is using for
its Sphinx documentation.  Older versions of Sphinx don't try to
parse the argument to c:function, so the only effect is incorrect
output, but Sphinx 3.0 does do this and will complain:
  Invalid C declaration: Expecting "," or ")" in parameters, got "EOF".

It looks like the kernel docs currently won't build at all
with Sphinx 3.0; https://github.com/sphinx-doc/sphinx/issues/7421
so I don't have an example of the error for the kernel docs.

QEMU is currently carrying another patch to our kernel-doc:
 https://patchew.org/QEMU/20200411182934.28678-1-peter.maydell@xxxxxxxxxx/20200411182934.28678-4-peter.maydell@xxxxxxxxxx/
which makes it use the new-in-3.0 "c:struct::" directive now
that "c:type::" no longer accepts "struct foo". Does anybody
have a plan for how the kernel kernel-doc is going to deal with
that non-back-compatible Sphinx change?
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f2d73f04e71d..f746ca8fa403 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -853,7 +853,7 @@ sub output_function_rst(%) {
 
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
-	    print $1 . $parameter . ") (" . $2;
+	    print $1 . $parameter . ") (" . $2 . ")";
 	} else {
 	    print $type . " " . $parameter;
 	}
-- 
2.20.1




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux