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

[Philippe Mathieu-Daudé]

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.