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

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

[Mahad Ibrahim]

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.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 Documentation/conf.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503a25..f2efe7fd107e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -227,6 +227,13 @@ c_id_attributes = [
     "__bpf_kfunc",
 ]
 
+# Since Sphinx 3.0, parameterized macros must be escaped using
+# c_paren_attributes to prevent C domain parser crashes.
+c_paren_attributes = [
+    #include/linux/compiler-context-analysis.h
+    "__cond_acquires",
+]
+
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
-- 
2.39.5

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@gmail.com> 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