From e32253508de412c3d91c55e73e099ddcc38e1082 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 31 Jan 2011 12:50:25 +0000 Subject: [PATCH] docs: Update documentation for ::destroy The ::destroy signal is meant to be used to break reference cycles on third party code. The documentation should really make it clear. --- clutter/clutter-actor.c | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 5c761fb0d..220d2d8a1 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -4319,11 +4319,22 @@ clutter_actor_class_init (ClutterActorClass *klass) /** * ClutterActor::destroy: - * @actor: the object which received the signal + * @actor: the #ClutterActor which emitted the signal * - * The ::destroy signal is emitted when an actor is destroyed, - * either by direct invocation of clutter_actor_destroy() or - * when the #ClutterGroup that contains the actor is destroyed. + * The ::destroy signal notifies that all references held on the + * actor which emitted it should be released. + * + * The ::destroy signal should be used by all holders of a reference + * on @actor. + * + * This signal might result in the finalization of the #ClutterActor + * if all references are released. + * + * Composite actors and actors implementing the #ClutterContainer + * interface should override the default implementation of the + * class handler of this signal and call clutter_actor_destroy() on + * their children. When overriding the default class handler, it is + * required to chain up to the parent's implementation. * * Since: 0.2 */