[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@xxxxxxxxx>
---
 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