Having a "\digit" inside a docstring with normal strings causes PDF output to break, as it will add a weird character inside the string. It should be using a raw string instead.
Yet, having r"\0" won't solve, as this would be converted in Sphinx as "0". So, this has to be inside a pre formatted text. That's said, the comment itself is probably not the best one. Rewrite the entire comment to properly document each parameter and add a "delim" parameter that will be passed to the ancillary function. Reported-by: Akira Yokosawa <[email protected]> Closes: https://lore.kernel.org/linux-doc/[email protected]/ Signed-off-by: Mauro Carvalho Chehab <[email protected]> --- tools/lib/python/kdoc/kdoc_re.py | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py index 886e33ffd2b9..f67ebe86c458 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -323,19 +323,28 @@ class NestedMatch: return args - def sub(self, sub, line, count=0): - """ - This is similar to re.sub: + def sub(self, sub, line, delim=",", count=0): + r""" + Perform a regex‑based replacement on ``line`` for all matches with + the ``self.regex`` pattern. It uses the following parameters: - It matches a regex that it is followed by a delimiter, - replacing occurrences only if all delimiters are paired. + ``sub`` + Replacement string that may contain placeholders in the form + ``\{digit}``, where ``digit`` is an integer referring to the regex + capture group number. - if r'\0' is used, it works on a similar way of using re.group(0): - it places the entire args of the matched paired data, with the - delimiter stripped. + ``\{0}`` is a special case that expands to the entire matched text. - If count is different than zero, it will replace at most count - items. + ``line`` + The string to operate on. + + ``delim`` + The delimiter used by identify the placeholder groups + (defaults to ","). + + ``count`` + Maximum number of replacements per match. If 0 or omitted, + all matches are replaced. """ out = "" @@ -355,7 +364,7 @@ class NestedMatch: # replace arguments new_sub = sub if "\\" in sub: - args = self._split_args(value) + args = self._split_args(value, delim=delim) new_sub = re.sub(r'\\(\d+)', lambda m: args[int(m.group(1))], new_sub) -- 2.52.0
