Re: [Qemu-devel] [PATCH v2 01/26] sysbus: document SysBusDeviceClass about @init

[Hu Tao]

On Wed, Jul 03, 2013 at 03:19:53AM +0200, Andreas Färber wrote:
> Am 01.07.2013 12:18, schrieb Hu Tao:
> > Signed-off-by: Hu Tao <address@hidden>
> > ---
> >  include/hw/sysbus.h | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> > 
> > diff --git a/include/hw/sysbus.h b/include/hw/sysbus.h
> > index 7c2e316..9614758 100644
> > --- a/include/hw/sysbus.h
> > +++ b/include/hw/sysbus.h
> > @@ -23,6 +23,16 @@ typedef struct SysBusDevice SysBusDevice;
> >  #define SYS_BUS_DEVICE_GET_CLASS(obj) \
> >       OBJECT_GET_CLASS(SysBusDeviceClass, (obj), TYPE_SYS_BUS_DEVICE)
> >  
> > +/*
> > + * SysBusDeviceClass:
> > + * @parent_class: This is private
> 
> Because it is private, the usual way is to suppress its documentation
> below via private/public markers.
> 
> > + * @init: Callback function invoked when the #DeviceState::realized 
> > property
> > + * is changed to %true. Deprecated, new types inheriting directly from
> > + * TYPE_SYS_BUS_DEVICE should use #DeviceClass::realize instead, new leaf
> > + * types should consult their respective parent type. SysBusDeviceClass is
> > + * not implementing #DeviceClass::realize, so deriving classes can simply
> > + * ignore it.
> > + */
> >  typedef struct SysBusDeviceClass {
> >      DeviceClass parent_class;
> >  
> 
> Thanks for documenting this. I'm queuing it with the following gtk-doc
> syntax and contential modifications, please let me know if you wish for
> any wording changes.

Thanks for the changes, looks OK to me.

> 
> Andreas
> 
> diff --git a/include/hw/sysbus.h b/include/hw/sysbus.h
> index 9614758..8c17165 100644
> --- a/include/hw/sysbus.h
> +++ b/include/hw/sysbus.h
> @@ -23,18 +23,20 @@ typedef struct SysBusDevice SysBusDevice;
>  #define SYS_BUS_DEVICE_GET_CLASS(obj) \
>       OBJECT_GET_CLASS(SysBusDeviceClass, (obj), TYPE_SYS_BUS_DEVICE)
> 
> -/*
> +/**
>   * SysBusDeviceClass:
> - * @parent_class: This is private
> - * @init: Callback function invoked when the #DeviceState::realized
> property
> + * @init: Callback function invoked when the #DeviceState.realized property
>   * is changed to %true. Deprecated, new types inheriting directly from
> - * TYPE_SYS_BUS_DEVICE should use #DeviceClass::realize instead, new leaf
> - * types should consult their respective parent type. SysBusDeviceClass is
> - * not implementing #DeviceClass::realize, so deriving classes can simply
> - * ignore it.
> + * TYPE_SYS_BUS_DEVICE should use #DeviceClass.realize instead, new leaf
> + * types should consult their respective parent type.
> + *
> + * SysBusDeviceClass is not overriding #DeviceClass.realize, so derived
> + * classes overriding it are not required to invoke its implementation.
>   */
>  typedef struct SysBusDeviceClass {
> +    /*< private >*/
>      DeviceClass parent_class;
> +    /*< public >*/
> 
>      int (*init)(SysBusDevice *dev);
>  } SysBusDeviceClass;
> 
> -- 
> SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg