The kernel-doc Sphinx plugin and associated script currently emit
'c:type' directives for "struct foo" documentation.
Sphinx 3.0 warns about this:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration.
If just a name:
Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
struct MemoryListener
------^
If typedef-like declaration:
Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 21]
struct MemoryListener
---------------------^
because it wants us to use the new-in-3.0 'c:struct' instead.
Plumb the Sphinx version through to the kernel-doc script
and use it to select 'c:struct' for newer versions than 3.0.
Fixes: LP:1872113
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
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 in the memory API documentation:
.. c:function:: void memory_region_init_resizeable_ram (MemoryRegion * mr, struct Object * owner, const char * name, uint64_t size, uint64_t max_size, void (*resized) (const char*, uint64_t length, void *host, Error ** errp)
which should have a ')' after the 'void *host' which is the
last argument to 'resized'.
Older versions of Sphinx don't try to parse the argumnet
to c:function, but Sphinx 3.0 does do this and will complain:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:834: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "EOF". [error at 208]
void memory_region_init_resizeable_ram (MemoryRegion * mr, struct Object * owner, const char * name, uint64_t size, uint64_t max_size, void (*resized) (const char*, uint64_t length, void *host, Error ** errp)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------^
Add the missing close-paren.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200411182934.28678-3-peter.maydell@linaro.org
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Surprisingly, QEMU does have a pretty consistent doc comment style and
it is not very different from the Linux kernel's. Of the documentation
"sigils", only "#" separates the QEMU doc comment style from Linux's,
and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in
accel/tcg/translate-all.c), so it's clear that the two standards are
different in this respect. In addition, our structs are typedefed and
recognized by CamelCase names.
Adjust kernel-doc's parser for these two aspects of the QEMU coding
standards. The patch has been valid, with hardly any change, for over
two years, so it should not be an issue to keep kernel-doc in sync with
the Linux copy.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Import Linux's kernel-doc script as of commit 15e2544ed38a1e, as well
as the Sphinx extension to call kernel-doc according to the arguments
and parameters given to a reStructuredText directive.
The kernel-doc extension accepts a filename, which is relative to
the QEMU source tree root. The extension also notifies Sphinx about the
document dependency on the file, causing the document to be rebuilt when
the file has been changed.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Peter Maydell
Paolo Bonzini