Re: [PATCH 8/9] docs/devel: mention the spacing requirement for QOM

["Philippe Mathieu-Daudé" <philmd@linaro.org>]

On 20/4/23 21:32, Mark Cave-Ayland wrote:
> On 20/04/2023 16:57, Alex Bennée wrote:
> 
>> We have a more complete document on QOM but we should at least mention
>> the style requirements in the style guide.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> Cc: Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>
>> ---
>>   docs/devel/qom.rst   |  2 ++
>>   docs/devel/style.rst | 29 +++++++++++++++++++++++++++++
>>   2 files changed, 31 insertions(+)


> A couple of points:
> 
> 1) It is probably worth removing the typedefs given that they are 
> handled by the various QOM macros
> 
> 2) There should be mention of the fixed names "parent_obj" and 
> "parent_class" for
> the first declaration.
> 
> How about something like this:
> 
> 
> QEMU Object Model Declarations
> ==============================
> 
> The QEMU Object Model (QOM) provides a framework for handling objects
> in the base C language. The first declaration of a storage or class
> structure should always be the parent and leave a visual space between

s/should/must/

> that declaration and the new code.
> 
> For a storage structure the first declaration should always be called
> "parent_obj" and for a class structure the first member should always
> be called "parent_class" as below:
> 
> .. code-block:: c
> 
>      struct MyDeviceState {
>          DeviceState parent_obj;
> 
>          /* Properties */
>          int prop_a;
>          char *prob_b;

Should we mention "We recommend placing instance/class properties fields
just after the parent field"?

>          /* Other stuff */
>          int internal_state;
>      };
> 
>      struct MyDeviceClass {
>          DeviceClass parent_class;
> 
>          void (*new_fn1)(void);
>          bool (*new_fn2)(CPUState *);
>      };
> 
> Note that there is no need to provide typedefs for QOM structures since 
> these are generated automatically by the QOM declaration macros. See 
> :ref:`qom` for more details.
> 
> 
> ATB,
> 
> Mark.