Re: [PATCH 4/5] qom/object.h: add missing documentation for object_class_* property functions

On Fri, Jul 17, 2026 at 01:56:05PM +0100, Mark Cave-Ayland wrote:
> On 17/07/2026 13:26, Daniel P. Berrangé wrote:
> 
> > On Fri, Jul 17, 2026 at 12:19:11PM +0100, Mark Cave-Ayland wrote:
> > > This is so that the object_class_* property functions appear in the generated
> > > QOM documentation at devel/qom-api.html.
> > > 
> > > Signed-off-by: Mark Cave-Ayland <[email protected]>
> > > ---
> > >   include/qom/object.h | 140 +++++++++++++++++++++++++++++++++++++++++++
> > >   1 file changed, 140 insertions(+)
> > > 
> > > diff --git a/include/qom/object.h b/include/qom/object.h
> > > index 11f55613fc..95fdf01e30 100644
> > > --- a/include/qom/object.h
> > > +++ b/include/qom/object.h
> > > @@ -1818,6 +1818,37 @@ ObjectProperty *object_property_add_link(Object *obj, const char *name,
> > >                                               Object *val, Error **errp),
> > >                                 ObjectPropertyLinkFlags flags);
> > > +/**
> > > + * object_class_property_add_link:
> > > + * @oc: the object class to add a property to
> > > + * @name: the name of the property
> > > + * @type: the qobj type of the link
> > > + * @offset: the offset from the object instance where the link object reference
> > > + *   is stored
> > > + * @check: callback to veto setting or NULL if the property is read-only
> > > + * @flags: additional options for the link
> > > + *
> > > + * Links establish relationships between objects.  Links are unidirectional
> > > + * although two links can be combined to form a bidirectional relationship
> > > + * between objects.
> > > + *
> > > + * Links form the graph in the object model.
> > > + *
> > > + * The @check() callback is invoked when object_property_set_link() is called
> > > + * and can raise an error to prevent the link being set. If @check is NULL, the
> > > + * property is read-only and cannot be set. Care must be taken to handle NULL
> > > + * values for @val.
> > > + *
> > > + * Ownership of the pointer that @child points to is transferred to the
> > > + * link property.  The reference count for *@child is
> > > + * managed by the property from after the function returns till the
> > > + * property is deleted with object_property_del().  If the
> > > + * @flags %OBJ_PROP_LINK_STRONG bit is set,
> > > + * the reference count is decremented when the property is deleted or
> > > + * modified.
> > 
> > Copy+paste mistake I presume - object_class_property_add_link does not
> > have a @child property, as this is only declaring the property on the
> > class, not setting the link's value on the object.
> 
> Interestingly enough I see that object_property_add_link() doesn't have a
> @child property either (it appears to have been changed to @targetp). I can
> easily fix that up in a separate patch.
> 
> How would we describe the ownership in terms of a class property? I'm not
> sure the last paragraph makes any sense given that a class property always
> exists. From looking at the code I think the last paragraph should simply
> read something like:
> 
> "If the @flags %OBJ_PROP_LINK_STRONG bit is set, the reference count of the
> linked object is incremented when the property is set, and decremented again
> when the property is modified."

Yeah that sounds reasonable..


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|