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

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."


ATB,

Mark.