[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 24/26] scripts/kerneldoc: For Sphinx 3 use c:macro for macros with
From: |
Peter Maydell |
Subject: |
[PULL 24/26] scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments |
Date: |
Mon, 2 Nov 2020 17:10:03 +0000 |
The kerneldoc script currently emits Sphinx markup for a macro with
arguments that uses the c:function directive. This is correct for
Sphinx versions earlier than Sphinx 3, where c:macro doesn't allow
documentation of macros with arguments and c:function is not picky
about the syntax of what it is passed. However, in Sphinx 3 the
c:macro directive was enhanced to support macros with arguments,
and c:function was made more picky about what syntax it accepted.
When kerneldoc is told that it needs to produce output for Sphinx
3 or later, make it emit c:function only for functions and c:macro
for macros with arguments. We assume that anything with a return
type is a function and anything without is a macro.
This fixes the Sphinx error:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/qom/object.h:155:Error
in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
Invalid C declaration: Expected identifier in nested name. [error at 25]
DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME)
-------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 39]
DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME)
---------------------------------------^
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Tested-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-id: 20201030174700.7204-2-peter.maydell@linaro.org
---
scripts/kernel-doc | 18 +++++++++++++++++-
1 file changed, 17 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ff62bb6a2d..4fbaaa05e38 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -839,7 +839,23 @@ sub output_function_rst(%) {
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ";
+ if ((split(/\./, $sphinx_version))[0] >= 3) {
+ # Sphinx 3 and later distinguish macros and functions and
+ # complain if you use c:function with something that's not
+ # syntactically valid as a function declaration.
+ # We assume that anything with a return type is a function
+ # and anything without is a macro.
+ if ($args{'functiontype'} ne "") {
+ print ".. c:function:: ";
+ } else {
+ print ".. c:macro:: ";
+ }
+ } else {
+ # Older Sphinx don't support documenting macros that take
+ # arguments with c:macro, and don't complain about the use
+ # of c:function for this.
+ print ".. c:function:: ";
+ }
}
if ($args{'functiontype'} ne "") {
$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
--
2.20.1
- [PULL 16/26] disas/capstone: Fix monitor disassembly of >32 bytes, (continued)
- [PULL 16/26] disas/capstone: Fix monitor disassembly of >32 bytes, Peter Maydell, 2020/11/02
- [PULL 19/26] hw/display/omap_lcdc: Fix potential NULL pointer dereference, Peter Maydell, 2020/11/02
- [PULL 15/26] target/arm: fix LORID_EL1 access check, Peter Maydell, 2020/11/02
- [PULL 18/26] hw/arm/boot: fix SVE for EL3 direct kernel boot, Peter Maydell, 2020/11/02
- [PULL 14/26] target/arm: fix handling of HCR.FB, Peter Maydell, 2020/11/02
- [PULL 20/26] hw/display/exynos4210_fimd: Fix potential NULL pointer dereference, Peter Maydell, 2020/11/02
- [PULL 21/26] target/arm: Get correct MMU index for other-security-state, Peter Maydell, 2020/11/02
- [PULL 23/26] hw/intc/arm_gicv3_cpuif: Make GIC maintenance interrupts work, Peter Maydell, 2020/11/02
- [PULL 22/26] configure: Test that gio libs from pkg-config work, Peter Maydell, 2020/11/02
- [PULL 25/26] qemu-option-trace.rst.inc: Don't use option:: markup, Peter Maydell, 2020/11/02
- [PULL 24/26] scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments,
Peter Maydell <=
- [PULL 26/26] tests/qtest/npcm7xx_rng-test: Disable randomness tests, Peter Maydell, 2020/11/02
- Re: [PULL 00/26] target-arm queue, Peter Maydell, 2020/11/03