On Wed, May 14, 2025 at 06:16:31PM +0200, BALATON Zoltan wrote:
> Date: Wed, 14 May 2025 18:16:31 +0200
> From: BALATON Zoltan <bala...@eik.bme.hu>
> Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
> OBJECT_DECLARE_SIMPLE_TYPE
>
> On Wed, 14 May 2025, Zhao Liu wrote:
> > On Wed, May 14, 2025 at 02:06:14PM +0200, BALATON Zoltan wrote:
> > > Date: Wed, 14 May 2025 14:06:14 +0200
> > > From: BALATON Zoltan <bala...@eik.bme.hu>
> > > Subject: Re: [PATCH 2/9] docs/devel/qom: Fix the doc about
> > > OBJECT_DECLARE_SIMPLE_TYPE
> > >
> > > On Wed, 14 May 2025, Zhao Liu wrote:
> > > > Currently, the expansion example of OBJECT_DECLARE_SIMPLE_TYPE "roughly"
> > > > reflects what OBJECT_DECLARE_TYPE is doing.
> > > >
> > > > Why "roughly"? Because this line -
> > > >
> > > > > G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > > >
> > > > - is also wrong for OBJECT_DECLARE_TYPE.
> > > >
> > > > Fix the expansion example of OBJECT_DECLARE_SIMPLE_TYPE, especially
> > > > drop that definition of MyDeviceClass.
> > > >
> > > > Cc: Paolo Bonzini <pbonz...@redhat.com>
> > > > Cc: "Daniel P. Berrang?" <berra...@redhat.com>
> > > > Cc: Eduardo Habkost <edua...@habkost.net>
> > > > Signed-off-by: Zhao Liu <zhao1....@intel.com>
> > > > ---
> > > > docs/devel/qom.rst | 11 +----------
> > > > 1 file changed, 1 insertion(+), 10 deletions(-)
> > > >
> > > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > > > index 5870745ba27b..185f4c2f5921 100644
> > > > --- a/docs/devel/qom.rst
> > > > +++ b/docs/devel/qom.rst
> > > > @@ -326,21 +326,12 @@ This is equivalent to the following:
> > > > :caption: Expansion from declaring a simple type
> > > >
> > > > typedef struct MyDevice MyDevice;
> > > > - typedef struct MyDeviceClass MyDeviceClass;
> > > >
> > > > - G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
> > > > + G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
> > > >
> > > > - #define MY_DEVICE_GET_CLASS(void *obj) \
> > > > - OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
> > > > - #define MY_DEVICE_CLASS(void *klass) \
> > > > - OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
> > > > #define MY_DEVICE(void *obj)
> > > > OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
> > > >
> > > > - struct MyDeviceClass {
> > > > - DeviceClass parent_class;
> > > > - };
> > > > -
> > > > The 'struct MyDevice' needs to be declared separately.
> > > > If the type requires virtual functions to be declared in the class
> > > > struct, then the alternative OBJECT_DECLARE_TYPE() macro can be
> > >
> > > Maybe you need to adjust the text here about OBJECT_DECLARE_TYPE here and
> > > show how to define Class sturct?
> >
> > Then it's not easy to organize the structure in this document, since
> > most of the content is now make "OBJECT_DECLARE_SIMPLE_TYPE" as well as
> > "OBJECT_DEFINE_SIMPLE_TYPE" as examples... I'm a bit unsure, and we can
> > wait and see what others would say.
> >
> > BTW, I found I missed this sentence:
> >
> > "(OBJECT_DECLARE_TYPE) This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> > but without the 'struct MyDeviceClass' definition."
> >
> > It should be: This does the same as OBJECT_DECLARE_SIMPLE_TYPE(),
> > but with the class type.
>
> Yes that's what I meant. If you remove the class example then how will
> readers know how to define that so a new example for that may be needed but
> you can wait for others' opinion too.
The new example deserves another separate patch. I'll think about how to
describe it.
Thanks,
Zhao
