Re: [PATCH trivial v2] plugins: add missing docstrings to qemu-plugin.h

On 10/03/2026 20:36, Pierrick Bouvier wrote:
> On 3/10/26 12:49 AM, Florian Hofhammer wrote:
>> This patch adds docstrings for typedefs and function declarations in
>> include/plugins/qemu-plugin.h that were previously missing. This
>> resolves inconsistencies in the docs, e.g., the description for
>> qemu_plugin_read_register() referring to qemu_plugin_register_flush_cb()
>> but code cache flush callbacks not being documented themselves.
>>
>> Signed-off-by: Florian Hofhammer <[email protected]>
>> ---
>> Hi,
>>
>> While working on a QEMU plugin and browsing the online docs at
>> https://www.qemu.org/docs/master/devel/tcg-plugins.html, I noticed that
>> some of the API functions were not actually documented.
>>
>> I went through the include/plugins/qemu-plugin.h header file and added
>> docstrings where they were missing, hoping of course that I documented
>> the correct functionality based on my understanding of the plugin
>> internals.
>>
>> I hope that's useful and I didn't miss anything!
>>
>> Best regards,
>> Florian
>>
>> Changes in v2:
>> - Added semantics clarification to the qemu_plugin_register_flush_cb()
>>    docstring (suggested by Pierrick)
>> - Link to v1: https://lore.kernel.org/qemu-devel/[email protected]
>> ---
>>   include/plugins/qemu-plugin.h | 101 +++++++++++++++++++++++++++++++++++++-----
>>   1 file changed, 91 insertions(+), 10 deletions(-)
>>
> 
> Thanks, looks good.
> It seems there are warnings (and thus errors) about missing parameters.
> Warning: /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 function parameter 'vcpu_idx' not described in 'qemu_plugin_vcpu_syscall_ret_cb_t'
> Warning: /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 function parameter 'vcpu_idx' not described in 'qemu_plugin_vcpu_syscall_ret_cb_t'
> WARNING: kernel-doc '/home/runner/work/qemu-ci/qemu-ci/build/pyvenv/bin/python3 /home/runner/work/qemu-ci/qemu-ci/docs/../scripts/kernel-doc.py -rst -enable-lineno -Werror /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h'

Hmmm, I should have caught that locally. My apologies! Seems I made a
mistake when copying docstring snippets: other functions use vcpu_index
as a parameter name, but qemu_plugin_vcpu_syscall_ret_cb_t uses
vcpu_idx. I adjusted the parameter name in the v3 series so that it
matches the docstring and the other functions' naming scheme.

> 
> Could you add those and check doc builds with warnings for v3?
> 
> Thanks,
> Pierrick

Best regards,
Florian