From 70a6acdce47d657f508ea7d31de735ee6c0de10d Mon Sep 17 00:00:00 2001 From: Yann SALMON Date: Tue, 18 Feb 2025 13:05:12 +0100 Subject: [PATCH 1/3] Fix dumping of parameters that are Func and not Par --- generator/generate.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/generator/generate.py b/generator/generate.py index 5844f24..13b3e39 100755 --- a/generator/generate.py +++ b/generator/generate.py @@ -667,10 +667,13 @@ def check(self): self.dump() sys.stderr.write(self.docs + "\n") - def dump(self, indent_lvl=0): + def dump(self, indent_lvl=0, out=()): for _ in range(indent_lvl): sys.stderr.write(_INDENT_) - sys.stderr.write("%s (%s): %s\n" % (self.name, self.type, self.source)) + + t = "Out" if self.name in out else "" + sys.stderr.write("%s (%s): %s %s\n" % (self.name, self.type, self.source, t)) + for p in self.pars: p.dump(indent_lvl + 1, self.out) From 2d9922263a5df2c86ec3fde5e035eee667fb3206 Mon Sep 17 00:00:00 2001 From: Yann SALMON Date: Tue, 18 Feb 2025 13:06:18 +0100 Subject: [PATCH 2/3] Partially fix regression in [OUT] parameter handling Part of the problem was that `Func.docs_in_sphinx_format` is called after `Par.flags` during generation, when the former method fills the `out` member of `Func`, on which the output of `Par.flags` depends. It resulted in out parameters being incorrectly flagged as in parameters (because it is the default). The concerned functions are: - `libvlc_log_get_context` - `libvlc_log_get_object`. --- generator/generate.py | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/generator/generate.py b/generator/generate.py index 13b3e39..e51cae4 100755 --- a/generator/generate.py +++ b/generator/generate.py @@ -2212,6 +2212,12 @@ def generate_funcs(self): for f in self.parser.funcs: name = f.name + # NOTE: `docs_in_sphinx_format` must be called before the `flags` method + # of `Par` instances, because it fills the `out` member (and other members) + # of the `Func`. If called after, `out` will be empty, resulting in missing + # out parameters in the bindings. + docs = self.add_sphinx_cross_refs(f.docs_in_sphinx_format()) + # make decorators for parameters that are function pointers pfs = {} for p in f.pars: @@ -2271,8 +2277,6 @@ def generate_funcs(self): types = ", ".join(types) - docs = self.add_sphinx_cross_refs(f.docs_in_sphinx_format()) - self.output(f"def {name}({args}):") self.generate_docstring(docs) self.output( @@ -2322,14 +2326,19 @@ def generate_func_pointer_decorator( """ indent = _INDENT_ * indent_lvl name = replacement_name if replacement_name else self.class4(pf.name) + + # NOTE: `docs_in_sphinx_format` must be called before the `flags` method + # of `Par` instances, because it fills the `out` member (and other members) + # of the `Func`. If called after, `out` will be empty, resulting in missing + # out parameters in the bindings. + docs = self.add_sphinx_cross_refs(pf.docs_in_sphinx_format()) + # return value and arg classes types = ", ".join( [self.class4(pf.type)] + [self.class4(p.type, p.flags(pf.out)[0]) for p in pf.pars] ) - docs = self.add_sphinx_cross_refs(pf.docs_in_sphinx_format()) - self.output(f"{indent}{name} = ctypes.CFUNCTYPE({types})") if docs: self.output(f"{indent}{name}.__doc__ = '''{docs}'''") From 1159442ad2cf4a49844ab186a1332228a73d0ce5 Mon Sep 17 00:00:00 2001 From: Yann SALMON Date: Tue, 18 Feb 2025 13:07:20 +0100 Subject: [PATCH 3/3] Fix regression in [OUT] parameters handling Out parameters that have documentation spanning multiple lines were not flagged as out parameters, because only the presence of `[OUT]` in the _first_ documentation line was checked. This commit fixes the issue be checking the presence of `[OUT]` in other lines as well. The concerned functions are: - `libvlc_media_discoverer_list_get` - `libvlc_media_player_get_full_chapter_descriptions` - `libvlc_media_player_get_full_title_descriptions` - `libvlc_media_slaves_get` - `libvlc_media_tracks_get` - `libvlc_renderer_discoverer_list_get` --- generator/generate.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/generator/generate.py b/generator/generate.py index e51cae4..2c49a39 100755 --- a/generator/generate.py +++ b/generator/generate.py @@ -700,6 +700,8 @@ def docs_in_sphinx_format(self, first=0) -> str: r = [] v = [] block = None + block_is_params = False + last_param_name = None lines = self.base_sphinx_format(self.docs) @@ -712,6 +714,7 @@ def docs_in_sphinx_format(self, first=0) -> str: if block is None: indent = "" block = heads + block_is_params = False # Check whether there is a blonk line right before the @code line. # If not, add one (needed for sphinx to properly display the list). @@ -726,22 +729,35 @@ def docs_in_sphinx_format(self, first=0) -> str: i += 1 block.append("") + block = None + block_is_params = False elif ":param" in line: + last_param_name = line.split()[1] + if _OUT_ in line: line = line.replace(_PNTR_, "") - out.append(line.split()[1]) + out.append(last_param_name) + params.append(param_re.sub(r":param \g:", line)) + block = params + block_is_params = True elif ":return:" in line: r.append(line) + block = r + block_is_params = False elif ":version:" in line: v.append(line) + block = v + block_is_params = False elif ":bug:" in line: b.append(line) + block = b + block_is_params = False elif "@code" in line: # we are dealing with a code block # Check whether there is a blonk line right before the @code line. # If not, add one (needed for sphinx to properly display the code block). @@ -781,20 +797,30 @@ def docs_in_sphinx_format(self, first=0) -> str: heads.append(line.replace("@endcode", "").strip()) block = None + block_is_params = False elif ".. note::" in line: if i - 1 >= 0 and lines[i - 1]: heads.append("") + heads.append(line) + block = heads + block_is_params = False elif ".. warning::" in line: heads.append(line) + block = heads + block_is_params = False elif block is not None: + if block_is_params and _OUT_ in line: + out.append(last_param_name) + if line: block.append(_INDENT_ + line) else: block.append(line) block = None + block_is_params = False else: heads.append(line)