diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 3620ca87a..ba82f524b 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -4981,6 +4981,10 @@ clutter_actor_destroy (ClutterActor *self)
  *
  * Also be aware that painting is a NOP for actors with an opacity of
  * 0
+ *
+ * When you are implementing a custom actor you must queue a redraw
+ * whenever some private state changes that will affect painting or
+ * picking of your actor.
  */
 void
 clutter_actor_queue_redraw (ClutterActor *self)