Re: [RFC PATCH v3 01/11] plugins: add types for callbacks related to certain discontinuities

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

On 12/5/24 04:44, Julian Ganz wrote:
> Hi Pierrick,
> 
> December 4, 2024 at 11:45 PM, "Pierrick Bouvier" wrote:
>> On 12/2/24 11:26, Julian Ganz wrote:
>>>   include/qemu/plugin.h | 1 +
>>>   include/qemu/qemu-plugin.h | 43 ++++++++++++++++++++++++++++++++++++++
>>>   2 files changed, 44 insertions(+)
>>>   diff --git a/include/qemu/plugin.h b/include/qemu/plugin.h
>>>   index 9726a9ebf3..27a176b631 100644
>>>   --- a/include/qemu/plugin.h
>>>   +++ b/include/qemu/plugin.h
> <snip>
>>> +
>>>   +/**
>>>   + * typedef qemu_plugin_vcpu_discon_cb_t - vcpu discontinuity callback
>>>   + * @vcpu_index: the current vcpu context
>>>   + * @type: the type of discontinuity
>>>   + * @from_pc: the source of the discontinuity, e.g. the PC before the
>>>   + * transition
>>>   + * @to_pc: the PC pointing to the next instruction to be executed
>>>   + *
>>>
>> Missing those parameters when building doc.
>> include/qemu/qemu-plugin.h:198: warning: Function parameter or member 'id' not described in 'qemu_plugin_vcpu_discon_cb_t'
>> include/qemu/qemu-plugin.h:289: warning: Function parameter or member 'type' not described in 'qemu_plugin_register_vcpu_discon_cb'
>> 2 warnings as Errors
> 
> Yes, I forgot about id. But type is clearly documented. Maybe the tool
> is confused about the name and thinks it's a reserved word or something?
> In that case I better change that to something else.
> 

The type (qemu_plugin_discon_type) is documented, but the parameter 
"type" is not. Even if the name is correctly chosen, you still need to 
make it appear in the doc.

> And note to self: also test-biuld the docs next time.
> 

I was bitten by this too when I started contributing to plugins, so no 
worries. It's safer to keep the docs enabled (that's the configure 
default), even if it adds some latency to the build, especially when 
touching documented headers.

> Regards,
> Julian Ganz