linux-kernel - Re: [PATCH] scripts/kernel-doc: Add missing close-paren in c:function directives

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200415151132.03cad507@lwn.net>
Date:   Wed, 15 Apr 2020 15:11:32 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Peter Maydell <peter.maydell@...aro.org>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Paolo Bonzini <pbonzini@...hat.com>
Subject: Re: [PATCH] scripts/kernel-doc: Add missing close-paren in
 c:function directives

On Tue, 14 Apr 2020 15:37:43 +0100
Peter Maydell <peter.maydell@...aro.org> wrote:

> 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:
> 
>  long work_on_cpu(int cpu, long (*fn) (void *, void * arg)
> 
> in driver-api/basics.html is missing a ')' separating the
> "void *" of the 'fn' arguments from the ", void * arg" which
> is an argument to work_on_cpu().
> 
> Add the missing close-paren, so that we render the prototype
> correctly:
> 
>  long work_on_cpu(int cpu, long (*fn)(void *), void * arg)
> 
> (Note that Sphinx stops rendering a space between the '(fn*)' and the
> '(void *)' once it gets something that's syntactically valid.)
> 
> Signed-off-by: Peter Maydell <peter.maydell@...aro.org>

Interesting.  This appears to have affected well over 100 function
definitions in the docs, and nobody ever noticed.  Good to know we're all
reading it closely :)

Applied, thanks.

> I noticed this first in the copy of kernel-doc that QEMU is using for
> its Sphinx documentation.  Older versions of Sphinx don't try to
> parse the argument to c:function, so the only effect is incorrect
> output, but Sphinx 3.0 does do this and will complain:
>   Invalid C declaration: Expecting "," or ")" in parameters, got "EOF".
> 
> It looks like the kernel docs currently won't build at all
> with Sphinx 3.0; https://github.com/sphinx-doc/sphinx/issues/7421
> so I don't have an example of the error for the kernel docs.
> 
> QEMU is currently carrying another patch to our kernel-doc:
>  https://patchew.org/QEMU/20200411182934.28678-1-peter.maydell@linaro.org/20200411182934.28678-4-peter.maydell@linaro.org/
> which makes it use the new-in-3.0 "c:struct::" directive now
> that "c:type::" no longer accepts "struct foo". Does anybody
> have a plan for how the kernel kernel-doc is going to deal with
> that non-back-compatible Sphinx change?

Thinking about 3.0 is on my list, but I've not gotten there yet.  I really
wish they wouldn't break things like that...

Thanks,

jon