On 20 August 2014 06:08, Peter Crosthwaite <peter.crosthwa...@xilinx.com> wrote: > With information about return value ownership. > > Signed-off-by: Peter Crosthwaite <peter.crosthwa...@xilinx.com> > --- > > include/qom/object.h | 6 ++++-- > 1 file changed, 4 insertions(+), 2 deletions(-) > > diff --git a/include/qom/object.h b/include/qom/object.h > index 8618e49..87de889 100644 > --- a/include/qom/object.h > +++ b/include/qom/object.h > @@ -1029,7 +1029,8 @@ Object *object_get_root(void); > * object_get_canonical_path_component: > * > * Returns: The final component in the object's canonical path. The > canonical > - * path is the path within the composition tree starting from the root. > + * path is the path within the composition tree starting from the root. The > + * returned value may not be modified. > */ > const gchar *object_get_canonical_path_component(Object *obj);
The other thing you need to say is that the returned string is only valid for as long as the object remains a child property of its parent. (Is that right? I'm not clear. It also sounds like a really awkward lifetime management requirement, which suggests to me that really the "return-a-copy" semantics are nicer.) Having object_get_canonical_path_component() and object_get_canonical_path() having different return value ownership semantics is likely to be a bit confusing I think. If we do do this I think I'd put the doc comment change in the same patch that changes the semantics. thanks -- PMM