Re: [PATCH] docs: fix Sphinx C parser crash on __cond_acquires macro

[Mauro Carvalho Chehab]

On Tue, 17 Mar 2026 11:11:56 -0400
Mahad Ibrahim <mahad.ibrahim.dev@xxxxxxxxx> wrote:

> When building the kernel-docs, the Sphinx C parser threw two errors:
> 
> 1. /home/code/linux/Documentation/core-api/kref:328:
>    ./include/linux/kref.h:72: WARNING: Invalid C declaration: Expected
>    end of definition. [error at 96]
>    int kref_put_mutex (
>                 struct kref *kref,
>                 void (*release) (struct kref *kref),
>                 struct mutex *mutex)
>                 __cond_acquires(true# mutex)
> 
> 2. /home/code/linux/Documentation/core-api/kref:328:
>    ./include/linux/kref.h:94: WARNING: Invalid C declaration: Expected
>    end of definition. [error at 92]
>    int kref_put_lock (
>                 struct kref *kref,
>                 void (*release)(struct kref *kref),
>                 spinlock_t *lock)
>                 __cond_acquires(true# lock)
> 
> The root cause of these errors is due to the parser's inability to
> understand sparse __cond_acquires() parameterized macro attached to the
> function. The parser expects a ';' or a '{' to verify a valid function
> signature ending.
> As of Sphinx 3.0, the parser is equipped to handle such cases via the
> c_paren_attributes list however that functionality was not adopted.
> 
> Out of all sparse/compiler-based context analysis parameterized macros
> inside the kernel, only __cond_acquires appears in the context of a
> kernel-docs comment and function, which is why it is the only macro that
> threw an error.
> 
> This bug may be attributed to the kernel's recent shift from sparse to
> compiler-based context analysis, increased strictness of Sphinx C
> parser, or some other change which transcended domains.
> 
> Add c_paren_attributes to enable Sphinx parser to handle parameterized
> function macros like __cond_acquires.

Sorry but this patch is going at the wrong direction, as this is
a kernel-doc issue. There are already a patch series under review
meant to handle this one, together with other related issues.

-- 
Thanks,
Mauro