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 <[email protected]>
---
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/[email protected]/[email protected]/
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
On Tue, 14 Apr 2020 15:37:43 +0100
Peter Maydell <[email protected]> wrote:
> 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 <[email protected]>
Interesting. This appears to have affected well over 100 function
definitions in the docs, and nobody ever noticed. Good to know we're all
reading it closely :)
Applied, thanks.
> 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/[email protected]/[email protected]/
> 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?
Thinking about 3.0 is on my list, but I've not gotten there yet. I really
wish they wouldn't break things like that...
Thanks,
jon
On Wed, 15 Apr 2020 at 22:11, Jonathan Corbet <[email protected]> wrote:
>
> On Tue, 14 Apr 2020 15:37:43 +0100
> Peter Maydell <[email protected]> wrote:
> > 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)
> Interesting. This appears to have affected well over 100 function
> definitions in the docs, and nobody ever noticed. Good to know we're all
> reading it closely :)
Heh; I think my conclusion is "function signatures for APIs which
don't provide and use a typedef for function-pointer-arguments are
sufficiently hard to read that people don't notice simple errors
in them", but then I prefer the with-typedef style to start with :-)
thanks
-- PMM