aboutsummaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-11-02 16:52:18 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-11-02 16:52:18 +0000
commit92bb29f9b2c3d4a98eef5f0db935d4be291eec72 (patch)
tree9ac0562c4f02c48786beaa466fcf2865be26b5e0 /scripts/kernel-doc
parentc20a135a7a14d846699b0cfc9f74bcc2a226bee6 (diff)
downloadqemu-92bb29f9b2c3d4a98eef5f0db935d4be291eec72.zip
qemu-92bb29f9b2c3d4a98eef5f0db935d4be291eec72.tar.gz
qemu-92bb29f9b2c3d4a98eef5f0db935d4be291eec72.tar.bz2
scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments
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
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc18
1 files changed, 17 insertions, 1 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ff62bb..4fbaaa0 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'} . " (";