[PATCH v2 25/28] docs: c_lex: better handle BEGIN/END at search

Mauro Carvalho Chehab
2026-03-12T14:55:02Z

Currently, the logic is emitting warnings after finishing
to parse a prototype like:

static inline unsigned \
read_seqretry(const seqlock_t *sl, unsigned start)
__releases_shared(sl) __no_context_analysis

The problem is that the last CMatch there doesn't have BEGIN/END,
but this is already expected.

Make the logic more restrict by:
- ensure that BEGIN/END there refers to function-like calls,
e.g. foo(...);
- only emit a warning after BEGIN is detected.

Instead of hardcoding "(" delim, let the caller specify if a different
one would be required.

While here, remove an uneeded elsif.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/lib/python/kdoc/c_lex.py | 23 +++++++++++++----------
1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/tools/lib/python/kdoc/c_lex.py b/tools/lib/python/kdoc/c_lex.py
index 8beac59166fc..e641bace5d69 100644
--- a/tools/lib/python/kdoc/c_lex.py
+++ b/tools/lib/python/kdoc/c_lex.py
@@ -463,8 +463,9 @@ class CMatch:
"""

- def __init__(self, regex):
+ def __init__(self, regex, delim="("):
self.regex = KernRe("^" + regex + r"\b")
+ self.start_delim = delim

def _search(self, tokenizer):
"""
@@ -506,15 +507,15 @@ class CMatch:
if tok.kind == CToken.SPACE:
continue

- if tok.kind == CToken.BEGIN:
+ if tok.kind == CToken.BEGIN and tok.value == self.start_delim:
started = True
continue
- else:
- # Name only token without BEGIN/END
- if i > start:
- i -= 1
- yield start, i
- start = None
+
+ # Name only token without BEGIN/END
+ if i > start:
+ i -= 1
+ yield start, i
+ start = None

if tok.kind == CToken.END and tok.level == stack[-1][1]:
start, level = stack.pop()
@@ -528,8 +529,10 @@ class CMatch:
# picking an incomplete block.
#
if start and stack:
- s = str(tokenizer)
- log.warning(f"can't find a final end at {s}")
+ if started:
+ s = str(tokenizer)
+ log.warning(f"can't find a final end at {s}")
+
yield start, len(tokenizer.tokens)

def search(self, source):
--
2.52.0