| Message ID | 20201030174700.7204-2-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Fix building with Sphinx 3.2 | expand |
On Fri, Oct 30, 2020 at 05:46:59PM +0000, Peter Maydell wrote: > 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> > --- > scripts/kernel-doc | 18 +++++++++++++++++- > 1 file changed, 17 insertions(+), 1 deletion(-) Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Regards, Daniel
On Fri, Oct 30, 2020 at 5:47 PM Peter Maydell <peter.maydell@linaro.org> wrote: > > 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> > --- > scripts/kernel-doc | 18 +++++++++++++++++- > 1 file changed, 17 insertions(+), 1 deletion(-) Tested-by: Stefan Hajnoczi <stefanha@redhat.com>
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'} . " (";
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> --- scripts/kernel-doc | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-)