On Fri, Oct 30, 2020 at 5:47 PM Peter Maydell <peter.mayd...@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.mayd...@linaro.org>
> ---
> scripts/kernel-doc | 18 +++++++++++++++++-
> 1 file changed, 17 insertions(+), 1 deletion(-)
Tested-by: Stefan Hajnoczi <stefa...@redhat.com>
