Re: [PATCH 1/9] qom/object: Improve the doc of macros related with simple type

[Zhao Liu <zhao1.liu@intel.com>]

Hi BALATON,

On Wed, May 14, 2025 at 02:02:48PM +0200, BALATON Zoltan wrote:
> Date: Wed, 14 May 2025 14:02:48 +0200
> From: BALATON Zoltan <balaton@eik.bme.hu>
> Subject: Re: [PATCH 1/9] qom/object: Improve the doc of macros related with
>  simple type
> 
> On Wed, 14 May 2025, Zhao Liu wrote:
> > There're 2 changes:
> > - For OBJECT_DECLARE_SIMPLE_TYPE:
> > 
> >   Since a clase may not only has virtual method, but also field, thus
> 
> class may not only have virtual methods but also fields, clarify when class
> is not needed

Thanks for the polish! It sounds better.

> >   mention when class is not needed for either, then there is no need
> >   to have the class.
> > 
> > - For OBJECT_DEFINE_SIMPLE_TYPE_WITH_INTERFACES:
> > 
> >   And the words like OBJECT_DEFINE_SIMPLE_TYPE about when the type is
> >   declared by OBJECT_DECLARE_SIMPLE_TYPE, then user should consider
> >   to define the type via OBJECT_DEFINE_SIMPLE_TYPE or
> >   OBJECT_DEFINE_SIMPLE_TYPE_WITH_INTERFACES.
> > 
> > Cc: Paolo Bonzini <pbonzini@redhat.com>
> > Cc: "Daniel P. Berrang?" <berrange@redhat.com>
> > Cc: Eduardo Habkost <eduardo@habkost.net>
> > Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
> > ---
> > include/qom/object.h | 5 +++--
> > 1 file changed, 3 insertions(+), 2 deletions(-)
> > 
> > diff --git a/include/qom/object.h b/include/qom/object.h
> > index 1d5b03372429..14f84ae454d3 100644
> > --- a/include/qom/object.h
> > +++ b/include/qom/object.h
> > @@ -249,7 +249,7 @@ struct Object
> >  * declared.
> >  *
> >  * This macro should be used unless the class struct needs to have
> > - * virtual methods declared.
> > + * virtual methods or fields declared.
> >  */
> > #define OBJECT_DECLARE_SIMPLE_TYPE(InstanceType, MODULE_OBJ_NAME) \
> >     typedef struct InstanceType InstanceType; \
> > @@ -402,7 +402,8 @@ struct Object
> >  *
> >  * This is a variant of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable for
> >  * the case of a non-abstract type, with interfaces, and with no requirement
> > - * for a class struct.
> > + * for a class struct. If you declared your type with OBJECT_DECLARE_SIMPLE_TYPE
> > + * then this is probably the right choice for defining it.
> 
> Is "probably" correct here? Is it a must or can still use other defining
> macros?

Yes, because there's another choice: OBJECT_DEFINE_SIMPLE_TYPE.

> If correct maybe saying "this might be the right choice" is simpler.

:-) I copied this sentence from the documentation of
OBJECT_DEFINE_SIMPLE_TYPE. The difference between these 2 macros is
OBJECT_DEFINE_SIMPLE_TYPE doesn't support interface.

So I'd like to keep this sentence, consistent with the description of
OBJECT_DEFINE_SIMPLE_TYPE.

Thanks,
Zhao